Pisanie dobrej dokumentacji: co napisać

Oryginalny post: Writing great documentation: What to write

Autor: Jacob Kaplan Moss

Dokumentacja techniczna może przybrać różnoraką formę - od wysokopoziomowego przeglądu, przez instrukcje krok po kroku, aż po automatycznie generowaną dokumentację API. Niestety, żaden format nie jest satysfakcjonujący dla wszystkich użytkowników; różnice w sposobie uczenia się ludzi są ogromne, a więc dobrze udokumentowane projekty muszą dostarczać dokumentacji pod wieloma postaciami.

W ogólnym ujęciu dokumentację, którą musisz dostarczyć, można podzielić na trzy różne formaty:

  • instrukcje krok po kroku,
  • dokumentację przeglądową i tematyczne przewodniki po różnych konceptualnych obszarach Twojego projektu oraz
  • niskopoziomowy materiał referencyjny, pozwalający zgłębić tajniki poszczególnych elementów.

Spójrzmy na każdy z nich po kolei.

Instrukcje krok po kroku

Dobre przewodniki są koniecznością, jako że zwykle są pierwszą rzeczą, jaką ktoś obejrzy zanim wypróbuje nowe urządzenie. Pierwsze wrażenie jest niesamowicie ważne: pośpiech, jaki Ci towarzyszy podczas przechodzenia dobrego tutoriala prawdopodobnie podbarwi Twoje przyszłe opinie na temat projektu.

Tutorial Django jest nieco już zmurszały i prawdopodobnie należy mu się przynajmniej małe odświeżenie, ale zachowuje najważniejsze reguły. Dobry przewodnik powinien:

  • Być szybki. Na pewnej konferencji usłyszałem kogoś - wydaje mi się, że była to Kathy Sierra - mówiącego że złotą zasadą jest, że nowy użytkownik powinien doświadczyć sukcesu w ciągu 30 minut. To świetna reguła: 30 minut to nic - pomyśl, pół godziny lunchu. Jeżeli Twój projekt może dać nowym użytkownikom te przyjemne doświadczenia tak szybko, odejdą zastanawiając się, jakie inne wspaniałe sukcesy może dać im dalsze zagłębienie się w projekt.

  • Być łatwy. Pamiętaj: chcesz, by wynikiem zastosowania przewodnika był sukces. Oznacza to, że będziesz musiał przetestować swój tutorial w każdych warunkach, upewniając się, że zawsze będzie działał (nawet na Windows).

  • Ale nie za łatwy. Zawsze będzie istniała pewna grupa użytkowników, którzy nie będą wystarczająco wykwalifikowani by korzystać z Twojego projektu. Ktoś, kto nigdy wcześniej nie napisał żadnego kodu nie zajdzie daleko z Django; ten rodzaj użytkowników powinien odpaść dość szybko. Nie pozwól im przejść przez tutorial tylko po to, żeby potem uderzyli głową w ścianę.

    Kolejnym, podobnym anty-wzorcem jest podkreślanie i wybłyszczanie swoich złych decyzji podjętych celem osiągnięcia doraźnej korzyści. Przewodnik Django popełnia ten błąd: chwalimy się rodzieleniem projektu/aplikacji w sposób, który później szkodzi użytkownikom. (Niedługo to naprawimy, obiecuję!).

    Najlepszym sposobem myślenia o "łatwości" przewodnika jest myślenie o nim jako o podjeździe do krzywej uczenia się projektu. Oznacza to, że początek może mieć więcej etapów niż późniejsze zadania (ale nie tak wiele, żeby nagle zadania te stały się dużo, dużo trudniejsze po ukończeniu tutoriala).

  • Zademonstruj, jak użytkownik może czuć się z Twoim projektem. Bardziej niż czegokolwiek innego, ludzie korzystają z Twojego przewodnika by sprawdzić, jak będą się czuli z Twoim projektem na dłuższą metę. Oznacza to, że przewodnik powinien być dość przekrojowy i pokazywać większość różnych obszarów Twojego projektu.

Kilka projektów z naprawdę dobrymi tutorialami do sprawdzenia celem inspiracji to LOVE i Lamson.

Przewodniki tematyczne

To jest rdzeń Twojej dokumentacji. Gdy tylko ktoś zrozumie (dzięki tutorialowi) wysokopoziomowe idee, będzie potrzebował zagłębić się w szczegóły tego czy innego obszaru. Jakakolwiek dokumentacja warta czegokolwiek będzie miała takich przewodników całkiem sporo; Django ma około 35 różnych przewodników tematycznych, poruszających każdą sferę (np. modele, sesje, testowanie, itp.).

Przewodniki te nie muszą pokrywać wszystkich szczegółów takich jak pojedyncza opcja konfiguracyjna czy argument funkcji - po to jest materiał referencyjny - ale każdy przewodnik (czy sekcja czy rozdział, zależnie od tego, jak jest to zorganizowane) musi znacząco zagłębić się w odpowiedni obszar.

Główną cechą pokrycia tematycznego powinna być wszechstronność. Czytelnik musi odejść od lektury czując się komfortowo w zadanym temacie. Powinien czuć, że zna większość możliwych opcji, i - co ważniejsze - powinien rozumieć, jak wszystkie elementy do siebie pasują.

Niestety, niewiele projektów radzi sobie z tym dobrze. Większość ma sensowne tutoriale, sporo ma całkiem niezłe materiały referencyjne, lecz większość zostawia przewodniki tematyczne książkom.

O ile prawdą jest, że książki wręcz lśnią w kwestii przewodników tematycznych, to nie są naprawdę dobrym substytutem przewodników będących częścią oficjalnej dokumentacji. Oficjalna dokumentacja, nawet kiepsko wykonana, jest zwykle znacznie bardziej na czasie; książki, nawet te napisane dobrze, są zwykle przeterminowane już z dniem trafienia na półki.

Książki-przewodniki mogą być zrobione dobrze - książka Subversion Book jest świetnym przykładem - ale tylko wtedy, gdy są ciągle uaktualniana i dostępne za darmo.

Istnieje pewien zgubny antywzorzec w dokumentacji - taki, w którym tutoriale są dostępne za darmo, ale prawdziwa dokumentacja jest dostępna tylko komercyjnie. W najlepszym wypadku, jest to leniwe i trudne; w najgorszym wypadku jest po prostu złe. Darmowe oprogramowanie potrzebuje darmowej dokumentacji. Jeśli postępujesz inaczej, powinieneś się wstydzić.

Materiał referencyjny

Na koniec potrzebujesz pełnego opisu wszystkich publicznych API, jakich dostarcza projekt. Opisy te powinny być stworzone dla tych, którzy wiedzą jak korzystać z niektórych API, ale potrzebują zajrzeć, jakich dokładnie argumentów oczekuje dana funkcja czy jaki wpływ na zachowanie ma dana opcja ustawień (i tym podobne).

Ważnym jest by podkreślić, że materiał referencyjny nie jest w żadnym stopniu zastępnikiem dobrych tutoriali i przewodników! Dobry materiał referencyjny dla pakietu foo.baz nie pomaga użytkownikom w żadnym stopniu, jeśli nie wiedzą, jakiego pakietu mają szukać.

Dokumentacja Pythona jest świetna pod tym względem. Sama biblioteka standardowa ma niesamowicie dobrą dokumentację; nie ma tam jednak wysokopoziomowych informacji pozwalających Ci znaleźć pakiet, którego szukasz! Weźmy na przykład kolekcje: jest to świetny materiał referencyjny mówiący o tym, co znajduje się w danym module, jak z tego skorzystać, jakie są jego wszystkie opcje. Jeśli jednak nie wiesz, że Python dostarcza implementacji kolejek dwukierunkowych (deque) w collections.deque, prawdopodobnie nie znajdziesz jej wcale.

Pomyśl o przewodnikach i materiałach referencyjnych jak o partnerach: przewodniki mówią Ci “dlaczego”, a materiał referencyjny mówi Ci “jak”. Wracając do przykładu kolejek dwustronnych, pewien rodzaj “przewodnika po strukturach danych w Pythonie” powinien dać Ci pojęcie o tym, jakie struktury danych możesz znaleźć w Pythonie (czy to wbudowanych, czy w bibliotece standardowej), i gdzie możesz znaleźć dokumentację do każdego z modułów celem znalezienia wszystkich szczegółów.

To bardzo kuszące, by użyć jakiegoś narzędzia do automatycznego dokumentowania - takiego jak Javadoc czy RDoc.

Nie rób tego.

Dokumentacja wygenerowana automatycznie jest niemalże bezużyteczna. W najlepszym wypadku jest to odrobinę lepsze od zwykłego przeglądania kodu, ale w większości wypadków jest znacznie łatwiej przejrzeć źródła niż nawigować przez te bzdury, jakie produkują narzędzia do generowania dokumentacji. Jedyną rzeczą, w której automatycznie generowana dokumentacja jest dobra, to wypełnianie zadrukowanych stron, gdy w umowie obiecano konkretną liczbę stron dokumentacji. Czuję głęboką wściekłość, gdy klikam w odnośnik, a on prowadzi mnie do dokumentacji wygenerowanej automatycznie.

Nie istnieje substytut dokumentacji napisanej, zorganizowanej i edytowanej ręcznie.

Posunę się nawet dalej i powiem, żę dokumentacja wygenerowana automatycznie jest nawet bardziej, niż bezużyteczna: pozwala myśleć opiekunom, że mają dokumentację, tym samym odwlekając napisanie rzeczywiście dobrego materiału referencyjnego ręcznie. Jeśli nie masz dokumentacji, po prostu się do tego przyznaj. Może jakiś ochotnik zgłosi się do napisania czegoś! Nie kłam jednak i nie wciskaj mi tych bzdur o auto-dokumentacji.

Co dalej

Jako że wiemy już co pisać, przejdę do jak to pisać. Jutro zaczniemy zagłębiać się w rzeczywiste mechanizmy rządzące pisaniem dobrej, czytelnej prozy technicznej.

Data publikacji oryginału: listopad 10, 2009

5 komentarze:

vshader pisze...

"Posunę się nawet dalej i powiem, żę dokumentacja wygenerowana automatycznie jest nawet bardziej, niż bezużyteczna (...)"
A co z dokumentacją generowaną automatycznie, ale wciągającą komentarze napisane "ręcznie", typu Doxygen bądź Javadoc? Wydaje mi się że stanowi złoty środek: zawiera zarówno pełne spisy klas, ich składników etc. jak również opisy zawarte w komentarzach (czyli stworzone "ręcznie"). Wydaje mi się to nawet lepsze niż dokumentacja tworzona osobno, jako że opis np. metody dla Doxygena jest zwykle pisany przez tę samą osobę która ją implementowała, a więc wie najlepiej co funkcja robi i jak reaguje na różne parametery.

Anonimowy pisze...

Co do doxygen i javadoc: w C/C++, gdzie jest podział na pliki nagłówkowe i pliki z implementacją, sensu to nie ma. Równie dobrze co dokumentację doxygen, można oglądać pliki nagłówkowe. Jedno i drugie zawiera to samo.

ShaXbee pisze...

@Anonimowy:
Nie chodzi o dokumentację wygenerowaną automatycznie z nieudokumentowanych nagłówków. Chodzi o dokumentację wygenerowaną na podstawie komentarzy zawierających dyrektywy doxygena umożliwiające opisanie roli parametrów, zwracanej wartości, rzucanych wyjątków etc. Developera interesuje właśnie dokumentacja API i dlatego tylko header wystarczy. Oczywiście sama dokumentacja API nie wystarczy, ale jest lepsza niż 'gołe' nagłówki.

Anonimowy pisze...

Właśnie te komentarze zawierające dyrektywy doxygena są tak samo czytelne podczas przeglądania nagłówków. Warto robić w nagłówkach komentarze, ale generowanie z nich dokumentacji jest niepotrzebne. Lepiej wyrzucić dyrektywy doxygena, czyniąc tym samym opisy bardziej zwięzłymi.

Anonimowy pisze...

Przeglądając kod nie masz wielu "ficzerów", takich chociażby jak diagramy wywołań, linki do powiązanych klas/metod itp.

Prześlij komentarz

Related Posts with Thumbnails