Spis treści

Typy dokumentacji

Poniżej znajduje się krótki opis typów dokumentacji akceptowanych na amp.dev:

Samouczek wprowadzający

Samouczki wprowadzające pomagają programiście zrozumieć ogólną koncepcję tej technologii. Zaczynają się od kodowania, a kończą kompletnym podstawowym projektem „Witaj świecie”. Samouczki wprowadzające pokazują, jak krok po kroku zbudować kluczową funkcję AMP. W samouczkach można stosować próbki kodu inline i/lub pobierane próbki, wymagające od programisty minimalnych poprawek w celu wykonania.

Przykłady amp.dev:

Dobrze	Źle
Podaj wskazówki z krótkimi wyjaśnieniami i jak najkrótszą procedurą.	Nie zagłębiaj się w niuanse projektu. Być może cel samouczka można osiągnąć na wiele sposobów, ale nie chodzi o to, aby przedstawić każdy z nich, tylko jeden, a dobry.
Zapewnij uproszczone środowisko i narzędzia do konfiguracji.	Nie zakładaj, że programista zna produkt i ma umiejętność kodowania na poziomie eksperckim.
Staraj się, by próbka była wizualnie uproszczona.	Nie komplikuj spraw ze względu na styl, chyba że samouczek dotyczy stylów.
Przedstaw zrzut ekranu z każdego kroku i gotowe demo.	Nie zapewniaj jedynie próbek kodu.
Utwórz wezwanie do działania. Wskaż programiście, na co ma zwracać uwagę.	Nie łącz przykładu z dalszym wyjaśnieniem. Jeśli uważasz, że nie ma wystarczających wskazówek dalszego postępowania, zastanów się nad złożeniem wniosku o opracowanie poradnika lub samouczka.

Samouczek zaawansowany

Samouczki zaawansowane pomagają programistom w wykonaniu określonego zadania. Zakłada się w nich, że programista ma pewną znajomość AMP. Samouczek powinien zademonstrować jak zbudować wrażenie, zintegrować funkcję lub opracować zadania wdrożeniowe.

Przykłady amp.dev:

Dobrze	Źle
Zapewnij instrukcje krok po kroku i zrozumiały projekt końcowy.	Nie przedstawiaj wyczerpujących szczegółów ani nadmiernie rozbudowanych koncepcji.
Zapewnij próbki kodu lub kod początkowy do pobrania. Dodatkowo udostępnij do pobrania ostateczny gotowy projekt.	Nie podawaj alternatywnych przykładów ani procesu do osiągnięcia wyniku końcowego.
Stwórz środowisko plug and play.	Nie podłączaj samouczka konfiguracji. Samouczki powinny być samodzielne.

Przewodnik wprowadzający

Przewodnik wprowadzający zawiera przegląd istotnych informacji, umożliwiających rozpoczęcie użytkowania technologii AMP. Powinien identyfikować funkcję, opisywać czym jest, a kończyć na tym, do czego służy. Przewodniki wprowadzające zapoznają programistę z podstawowymi wymaganiami dotyczącymi danej funkcji, nie kierując go do jej wdrożenia. Jeśli przechodzisz przez proces krok po kroku z próbkami kodu, prawdopodobnie piszesz samouczek. Jeśli opisujesz wszystkie elementy programistyczne składnika AMP, prawdopodobnie piszesz dokument referencyjny.

Przykłady amp.dev:

Dobrze	Źle
Zidentyfikuj treść dokumentu.	Nie rozkładaj go na poszczególne kroki procesu.
Przedstaw cechy i koncepcje. Zamieść link do dokumentów referencyjnych zawierających szczegółowe informacje na temat zaawansowanego użytkowania.	Nie opisuj wyczerpująco. w szczegółach
Zapewnij próbki kodu i rzeczywiste przykłady.	Nie twórz całej aplikacji. Zamiast tego podaj link do przykładów lub różnych wersji demo do dalszej analizy.
Podaj listę zastosowań technicznych i ograniczeń.	Nie wymieniaj wszystkich możliwych zastosowań technicznych i sposobów ich wykonania.

Przewodnik po koncepcji

Przewodniki po koncepcji pomagają programistom pogłębić wiedzę na temat AMP. Przewodnik po koncepcji jest jak mapa topograficzna — przedstawia różne szlaki w okolicy z takimi szczegółami jak zmiany wysokości terenu, ale nie wyznacza konkretnej trasy. Wyjaśniaj, czym jest funkcja i jak działa, a nie jak ją skonstruować.

Przykłady amp.dev:

Dobrze	Źle
Zapewnij programiście wszystkie elementy potrzebne do skonstruowania rozwiązania.	Nie prowadź aktywnie programisty do określonego stanu końcowego.
Omów wszystkie zagadnienia z zakresu tematycznego.	Nie skupiaj się na konkretnym zadaniu.
Dodaj pomoce wizualne, takie jak schematy lub zrzuty ekranu.	Nie myśl za dużo, możesz poprosić o pomoc w zapewnieniu materiałów wizualnych w grupie roboczej ds. kontaktów zewnętrznych [outreach working group](https://github.com/ampproject/wg-outreach).
Zapewnij próbki kodu i linki do innych przewodników.	Nie udostępniaj gotowego projektu do pobrania ani nie zbaczaj z tematu.

Dokumentacja referencyjna

Dokumentacja referencyjna zawiera listę wszystkich elementów programistycznych składnika AMP. Dostarcza szczegółowych informacji o sposobie działania i jest przeznaczona do przeszukiwania. Dokumentacja referencyjna powinna zawierać próbki przykładowego kodu oraz przykłady użycia.

Dokumenty referencyjne amp.dev znajdują się w katalogu składników AMP.

Dokumentację referencyjną AMP należy przekazywać do repozytorium AMPHTML.

Dobrze	Źle
Używaj zrozumiałego i zwięzłego języka, aby wyjaśnić jak działa dany składnik.	Nie wyjaśniaj procesu ani nie twórz projektu.
Porządkuj dokument za pomocą łatwych do wyszukania tytułów, nagłówków i śródtytułów.	Nie grupuj treści pod abstrakcyjnymi nazwami.
Przedstaw fragmenty kodu, demonstrujące użycie składników.	Nie twórz pełnych aplikacji demonstracyjnych.

Written by @CrystalOnScript