Pisanie dobrej dokumentacji: styl

Oryginalny post: Writing great documentation: Technical style

Autor: Jacob Kaplan Moss

Jako że omówiliśmy już jakie rodzaje dokumentacji należy tworzyć, możemy przejść do odpowiedzi na pytanie jak należy rozwinąć styl, dzięki której taką dokumentację będzie dało się czytać.

Naucz się pisać

Niestety, nie ma tutaj dróg na skróty. Najlepszym sposobem na nauczenie się jak pisać dobrą dokumentację jest najpierw nauczyć się pisać (cokolwiek). Istnieją pewne istotne różnice między dokumentacją techniczną i Twoją przeciętną prozą, ale solidne podstawy w komunikacji pisemnej są wymaganiem nie do zastąpienia.

Więc jak nauczyć się pisać (cokolwiek) dobrze? Jest tylko jedna odpowiedź: nauczysz się pisać dobrze, jeśli będziesz pisał. Dużo.

Pisanie po angielsku nie różni się niczym od pisania kodu: im więcej piszesz, tym lepiej to robisz. Mógłbyś wziąć lekcję - większość szkół ma całkiem niezłe lekcje dla początkujących - ale ważnym jest, żeby po prostu dużo pisać. Po pewnym czasie będzie lepiej.

To właśnie tak Ci z nas, którzy uzyskali tytuły z nauk humanistycznych (mam tytuł z literatury angielskiej, znany także jako B.A. in B.S.) stają się dobrymi pisarzami: nasze tytuły zmuszają nas do pisania tak długo, aż zacznie przychodzić nam to z łatwością. Myślę, że pisałem od dziesięciu do dwudziestu stron każdego tygodnia w ciągu czterech lat studiów. Zmusiło mnie to do przyswojenia zasad gramatyki i ukształtowania własnego stylu.

Prawdopodobnie dobrze byłoby zbalansować ilość pisanego tekstu zdrową ilością tekstu czytanego. Naucz się określać mechaniczne części tego, co czyni kawałek tekstu efektywnym; spróbuj zidentyfikować, co przynosi sukces, a co porażkę we wszystkim co czytasz.

Zwróć uwagę na to, co pozwala autorom uzyskać "ton". Przeczytaj pewną ilość tekstów tego samego autora; powinieneś być w stanie zidentyfikować to, co czyni teskty tej osoby odróżnialnymi od innych. Malcolm Gladwell byłby tutaj dobrym wyborem: jego styl jest dość wyróżniający się, w pewien sposób wzorcowy, a także ma tuziny swoich artykułów dostępnych online. Co najważniejsze, styl Gladwell'a jest jednym z tych, które dość dobrze nadają się dla dokumentacji technicznej - ma odświeżający, zabawny, konwersacyjny ton, który przekazuje jasno techniczne zagadnienia.

Nie ma wielkiego znaczenia, co piszesz i czytasz. Jasne, istnieją osobne zasady pisania fikcji i nie-fikcji, literackiego krytycyzmu i dokumentacji technicznej, itd. Ważne aspekty się jednak nie zmieniają: dobry tekst jest jasny, zwięzły i efektywnie przekazuje idee.

Najważniejsze: nie pozwól swojemu stylowi Cię zatrzymać. Za chwilę przejdę do zasad i wskazówek dotyczących dobrej gramatyki i stylu. Łatwo dać się złapać w pułapkę prozy idealnej od pierwszych słów. To tak nie działa. Podczas pisania, ucisz wewnętrznego krytyka i po prostu pisz. Możesz pozwolić krytykowi przemówić, gdy czytasz i poprawiasz napisany tekst, ale ważnym jest żeby to po prostu zrobić. Nie pozwól proszę, żeby cokolwiek, o czym wspomnę za chwilę, stanęło Ci na drodze.

Gramatyka

Tak, musisz używać poprawnej gramatyki. Konwencje w gramatyce istnieją po to, by pomóc nam jasno przekazać swoje myśli bez niejednoznaczności czy dezorientacji. Musisz zrozumieć różnicę pomiędzy "its" oraz "it's;" między "there," "they're" i "their;" musisz też zrozumieć, dlaczego wstawiam przecinki w tym zdaniu wewnątrz cudzysłowów, a nie na zewnątrz. (Jako że moi słuchacze to głównie programiści, nie powinienem spędzać dodatkowego czasu nad tłumaczeniem, dlaczego spójne ustawianie średników jest tak ważne!)

Jeśli chodziłeś do publicznej szkoły w Stanach, prawdopodobnie się tego nauczyłeś. Jeśli Twoja szkoła była jakkolwiek podobna do mojej, prawdopodobnie zapomniałeś o tym wszystkim krótko po tym, jak tą szkołę opuściłeś.

Tak więc lekcje pisania mogłyby pomóc, jeśli lubisz się uczyć w taki sposób. Ja sam mam kilka książek, które zawsze mam pod ręką:

  • The Elements of Style Strunk'a i White'a jest prawdopodobnie najbardziej znaną książką na temat gramatyki i stylu. Jej zwięzły i dowcipny styl sprawia, że czyta się ją z prawdziwą przyjemnością - bardzo nietypowe dla tekstów o gramatyce. Jest odrobinę stara (w istocie, pojawiło się ostatnio kilka sprzeciwów przeciw radom serwowanym przez S&W), ale jeśli potraktujesz serio Strunk'a i White'a, wyprzedzisz o głowę przeciętnego pisarza.

    (Istnieje piękna edycja z okazji pięćdziesięciolecia, jeśli pragniesz zostać posiadaczem edycji stosownej do zawartości).

  • A Pocket Style Manual Diany Hacker. To jest sensowny, podręczny przewodnik po gramatyce, interpunkcji i mechanice. Jako dodatek, ma odnośniki do przewodników Chicago Manual, Modern Language Association (MLA) i American Psychological Association (APA).

  • Mimo że rzadziej z niej korzystam, uważam że Handbook of Technical Writing jest całkiem użyteczna. Jest to olbrzymi, obszerny przewodnik od A do Z po języku - jest rozdział o "its" i "it's," jeden o "no doubt but", i tak dalej. (Jestem pewien, że jest tam rozdział o "i tak dalej.") Nie polecałbym zaczynania od tej publikacji; korzystaj z niej raczej jako z podręcznika do wyszukania zasad dotyczących konkretnego sformułowania.

Styl

Moment. Czym są przewodniki po stylu?

Podczas gdy zasady gramatyki są (raczej) utrwalone, jest mnóstwo sposobów na sformalizowanie stylu. Przewodniki po stylu mówią Ci, kiedy wykorzystywać liczebniki, a kiedy zapisywać je jako liczby, kiedy korzystać z krótkich, a kiedy z długich myślników, jak cytować źródła i zawierają wszelkie inne zasady sztuki.

Trzy, które omawia Hacker - Chicago Manual, MLA oraz APA - to jedne z najpowszechniejszych używanych w publikacjach akademickich. The Chicago Manual jest popularny w socjologii i historii; MLA jest używany przez większość publikacji literackich, medialnych i kulturalnych; APA formułuje podstawy dla przewodników stylu dla publikacji naukowych. Jest jeszcze sporo innych przewodników po stylu - duże publikacje takie jak New York Times czy New Yorker mają własne przewodniki. Jeżeli jednak nie jesteś językowym świrem, to jest to raczej nudna lektura.

Dokumentacja Django czerpie głównie z książki Associated Press, składając w ten sposób swego rodzaju hołd korzeniom prasowym Django.

Summa summarum, nie ma jednak olbrzymiej różnicy. Ważnym jest, żeby z tego wszystkiego zapamiętać, żeby być spójnym. Czytelników odrzuca mnogość stylów, a te wprowadzają niezrównoważony, niedokończony ton dokumentacji. Wybierz styl, naucz się go, a później się go trzymaj... czasami.

Styl dobrej dokumentacji

Oczywiście, ostrożne łamanie zasad czyni dobry tekst lepszym. Większość zasad, które znajdziesz w tych przewodnikach, jest zorientowanych w stronę publikacji akademickich; ja jednak staram się pomóc Ci pisać lepszą dokumentację. Są pewne istotne różnice. Większość przewodników po stylach zakłada, że efekt końcowy będzie prezentowany w formie papierowej; większość dokumentacji technicznej jest jednak wykorzystywana on-line.

Jest to prawdopodobnie powszechnie wiadome, że ludzie czytają inaczej z ekranu komputera; prawdopodobnie jest też prawdą, że ludzie inaczej czytają dokumentację techniczną niż materiały naukowe.

Zatem, pozostała część tego artykułu będzie omawiać obszary, w których dobra dokumentacja narusza zasady dobrego stylu opisanego przez S&W, Hacker, i innych.

Adjustacja

Jest pewna olbrzymia różnica w sposobie, w jaki ludzie czytają słowo drukowane i słowo elektroniczne: gdy ludzie czytają materiały online, prześlizgują się po niej. Kolejne badania wykazały, że czytelnicy opuszczają spory odsetek słów widocznych na ekranie komputera.

Oznacza to, że dobra dokumentacja online będzie opierała się w znacznie większym stopniu na znacznikach, niż pozwala większość przewodników po stylach. W praktyce oznacza to:

  • Swobodnie korzystaj ze znaczników.

    Głównie oznacza to częste wykorzystywanie podkreśleń i uwydatnień. Ja zwykle staram się unikać zbyt wielu uwydatnień ponieważ wygląda to jakbym małpował Jakoba Nielsena, ale co tam. Podobnie, korzystaj ze znaczników dla rzeczy takich jak fragmenty kodu, wejście kontra wyjście i tym podobne.

    Przełamuje to monotonię dużych kawałków tekstu i pozwala użytkownikom prześlizgiwać się pomiędzy różnymi "ważnymi" częściami tekstu.

  • Niech Twoje paragrafy będą krótkie.

    Jeśli porównasz dobrą dokumentację do typowego artykułu w magazynie czy rozdziału książki, szybko zauważysz olbrzymią różnicę w rozmiarze paragrafów. Książka może mieć paragrafy złożone z dziesięciu, dwudziestu, czy tuzinów zdań; rzadko jednak dokumentacja online ma choćby połowę z tego. Najdłuższe paragrafy w tym tekście mają około 5-6 zdań.

    Ponownie, czytelnicy prześlizgują się po cyfrowym dokumencie. Dzielenie Twoich myśli na mniejsze kawałki wspiera ten sposób poruszania się po tekście i zapewnia, że ważne elementy nie zostaną pominięte tylko dlatego, że są zakopane w środku ściany tekstu.

  • Wykorzystuj różnorodne elementy strukturalne.

    Piśmiennictwo akademickie czy żurnalowe nie wykorzystuje wypunktowań, tabel, bloków kodu i tym podobnych. Większość przewodników po stylach pomija je, a nawet zabrania ich wykorzystywania. Te elementy są jednak kluczowe dla dokumentacji technicznej: tabele i wypunktowania są ważnymi sposobami przedstawiania materiału.

    Komentarz

    Wyróżnione części listingu lub wyróżnione objaśnienia do rysunków są wyjątkowo przydatne; przykuwają uwagę do tych kawałków zawartości, które w przeciwnym wypadku mogłyby umknąć, dostarczają zabawnych i interesujących dygresji lub wskazują na to, że dany fragment jest wyjątkowo istotny.

  • Uczyń strukturę tekstu widoczną.

    Twój nauczyciel angielskiego prawdopodobnie uczył, że nagłówki do sekcji są "w złym stylu" i że cały tekst razem wzięty powinien "płynąć". To "płynięcie" jest bardzo istotne, ale trudne do osiągnięcia w tekstach technicznych. Jeśli się uprzesz, zostaniesz z bezsensownymi przejściami: "jako że omówiliśmy już adresy URL, porozmawiajmy o modelach!".

    Nagłówki są wyjątkowo ważne: zatrzymają czytelników przelatujących po tekście. Nagłówki pomagają czytelnikowi szybko odnaleźć interesującą ich sekcję dokumentu.

Powyższe może się wydawać oczywiste tym, którzy publikowali w sieci od jakiegoś czasu. O to chodzi; większość dokumentacji technicznej jest czytania online, więc większość tych rad sprowadza się do optymalizacji zawartości pod czytanie online. Dokumenty zaprojektowane pod druk cierpią, gdy są czytane online; tak więc, jeśli tylko czytasz o stylu, zawsze zastanów się nad tym, czy dana rada ma zastosowanie online.

Styl

Czytelnicy materiałów online mają inne oczekiwania w kwestii stylu. Istnieje pewien styl, który nadaje się do materiałów online i wspiera proces nauczania - który dokumentacja wspierać powinna.

Sprowadza się to głównie do bycia osiągalnym. Większość przewodników po stylu jest zorientowanych w stronę środowisk akademickich, a publikacje akademickie są wiecznie formalne. Oczekiwania wobec dokumentu online są inne i to, co może być stosowne dla żurnalu dla krytyków literackich jawi się jako przestarzałe i głupie w środowisku online.

Sugeruję więc:

  • Utrzymaj styl konwersacyjny.

    Pisz w sposób podobny do tego, w jakim mówisz. Nie chodzi o to, żeby korzystać z tych wszystkich werbalnych przeszkadzajek ("well", "you see", "um...") ani też zupełnie porzucać zasady gramatyki. Jeśli korzystasz z "gonna" w dokumencie technicznym, znienawidzę Cię ("I'm gonna hate you).

    Nie mniej jednak to znaczy, że skróty sa w porządku - tak samo jak zaczynanie zdań od spójników.

  • Nie obawiaj się uderzyć w osobisty ton.

    Prawdopodobnie nauczyłeś się nigdy nie korzystać z "ja" w formalnym wypracowaniu. Cóż, jestem tu by Ci powiedzieć, że to zupełnie w porządku w tekstach technicznych. Ukazywanie swojej osobistej opinii pomaga czytelnikom identyfikować się z tekstem i czyni materiał mniej odstraszającym.

    Musisz być ostrożny i spójny w kwestii zaimków we wspólnych pracach. Możesz zdecydować się na wyłączne używanie "ja," nawet w pracach pisanych przez innych autorów. Leonard Richardson i Sam Ruby obrali tą drogę w RESTful Web services. Możesz też użyć "my", nawet w częściach napisanych przez jednego autora. Adrian I ja wybraliśmy ten sposób w Django book. Tak długo, jak pozostajesz spójny, każde z podejść się nadaje.

  • Bądź ostrożny z czasami i osobami.

    Większość dokumentacji, a zwłaszcza tutoriale, jest napisana w drugiej osobie, w czasie przyszłym. To teksty typu "Po pierwsze, będziesz musiał zainstalować FooBar w wersji 7. Następnie, gdy już skonfigurowałeś whizbang, możesz zacząć pracę z doodad". To jest ogólny sposób, który preferuję, jako że dokumentacja to materiał głównie instruktażowy, a ja lubię to próżne poczucie osobistego kierowania czytelnikami.

    Kolejnym powszechnym sposobem jest wyrażanie wszystkiego w pierwszej osobie liczby mnogiej: "Po pierwsze, musimy zainstalować FooBar w wersji 7..." To ma swoje zalety: implikuje, że autor jest tuż obok, wśród ogromu rzeczy wokół czytelnika. Może to jednak prowadzić do pewnego zagmatwania, gdy autor naraz zacznie próbować przejść na styl bardziej konwersacyjny.

    I znów, nie ma "poprawnego" sposobu; będziesz jednak chciał przemyśleć tą sprawę, utworzyć standard, a później się go trzymać.

  • Uważaj na tryb bierny.

    Prawdopodobnie nauczyłeś się unikać strony biernej w swoich tekstach. To zwykle dobra rada, ale to nie wszystko; to, co mam na myśli, to to, że dobry tekst techniczny jest napisany w stronie czynnej. Czasownik zawsze pojawia się pierwszy. Pamiętaj: instruujesz ludzi, więc musisz za każdym razem jasno powiedzieć im, co mają zrobić.

    By to zilustrować, mój pierwszy szkic powyższego paragrafu zaczynał się od "Twoje lekcje angielskiego prawdopodobnie nauczyły Cię, że strona bierna jest w złym stylu". To nie jest strona bierna ("Lekcje angielskiego... nauczyły..." jest dość aktywna), ale zaciemnia istotę zdania - akcję "nauczyłeś się". Zaczynanie każdego z dnia od "nauczyłeś się" przywraca skupienie na Ciebie, czytelnika, utrzymując konwersacyjny, instruktażowy ton, w który staram się celować.

  • Pomiń puch.

    Najlepiej pokazać to na przykładzie. Wczorajszy tekst zawierał takie paskudne zdanie:

    Oznacza to, że powinien być całkiem przekrojowy; dobry tutorial powinien chwalić większość różnych obszarów projektu.

    Mój komentator (prawidłowo) skomentował to tak: to zdanie ma sporo słów ("całkiem", "większość", "dobry") które nie dodają żadnego znaczenia zdaniu, a niektóre z pozostałych ("różne obszary", "projekt") są niejasne.

    Poniżej jest lepsza wersja:

    Oznacza to, że powinien być przekrojowy; dobry tutorial powinien chwalić różne obszary Twojego projektu.

    Znaczenie pozostaje to samo, ale druga wersja ma więcej mocy, jest jaśniejsza i krótsza. A to dobrze.

  • Uważaj na pisemne tiki.

    Każdy ma pewne złe nawyki jeśli chodzi o pisanie. Myślę o tym jako o pisarskich tikach: drobnych zwyczajach, które stały się niemal nieumyślne. Jak tylko zauważysz tiki autora, trudno przestać zwracać na nie uwagę. Powtórzenie po prostu przeszkadza.

    Żeby było jasne, moimi tikami są opieranie się na średnikach i myślnikach; ten dokument zawiera o wiele za dużo każdego z nich.

Co dalej

Wszystkie te zasady mogą być niesamowicie przytłaczające, wiem. Nie mniej jednak, istnieje magiczne stworzenie, które zna je wszystkie i zastosuje je do Twojego tekstu, a Ty nie będziesz musiał tego robić

Opowiem o tych magicznych istotach w jutrzejszym odcinku zatytułowanym: "Potrzebujesz edytora".

Część serii Pisanie dobrej dokumentacji.

Data publikacji oryginału: listopad 11, 2009

Nowi moderatorzy na devPytaniach

Zapewne większość z Was dobrze zna serwis devPytania. Przypomnijmy sobie, jak on funkcjonuje:

To nie my tworzymy devPytania. Wy to robicie. devPytania to serwis budowany i utrzymywany wspólnymi siłami Twoich kolegów programistów. Gdy serwis dostatecznie Ci zaufa, będziesz mógł edytować wszystkie treści, podobnie jak na Wikipedii. Z Twoją pomocą jesteśmy w stanie udzielić dobrej odpowiedzi na praktycznie każde możliwe pytanie programistyczne. Nie ma znaczenia język programowania czy system operacyjny, którego używasz — naszym celem jest lepsze programowanie.

Aby powyższe było możliwe, dostarczony został system punktów reputacji:

Zgromadź wystarczającą liczbę punktów reputacji, a serwis devPytania pozwoli Ci na wiele więcej niż zwykłe zadawanie pytań i udzielanie odpowiedzi:

15Oddawaj pozytywne głosy.
15Oznaczaj nieodpowiednie treści.
50Pisz komentarze.
100Oddawaj negatywne głosy (kosztuje to 1 punkt reputacji). Edytuj wpisy będące częścią społecznościowego wiki.
200Zmniejsz ilość reklam.
250Głosuj za zamknięciem bądź ponownym otwarciem własnych pytań. Twórz nowe tagi.
500Zmieniaj pytaniom tagi.
2000Edytuj treść innych użytkowników.
3000Głosuj za zamknięciem bądź ponownym otwarciem dowolnych pytań.
10000Kasuj zamknięte pytania. Uzyskaj dostęp do narzędzi moderatora.

Na końcu tego spektrum reputacji różnica między użytkownikami z wysoką reputacją a moderatorami jest niewielka. Właściwość ta jest całkowicie zamierzona. To nie my prowadzimy serwis devPytania. Robi to społeczność.

Niemniej jednak mimo istnienia aktywnej, samoregulującej się społeczności, moderatorzy muszą interweniować od czasu do czasu. Moderatorzy zajmują się tymi niezwykle rzadkimi sytuacjami, które nie powinny się normalnie wydarzać, ale jeśli już się wydarzą, to potrafią znacząco zaburzyć działanie społeczności.

Tak więc, co może moderator na devPytaniach?

  • Głos moderatora jest wiążący. W jakimkolwiek miejscu, gdzie występuje głosowanie (zamykanie, otwieranie, kasowanie, odzyskiwanie, itp), głos moderatora powoduje osiągnięcie progu i zaaplikowania danej akcji natychmiast.
  • Moderator może zablokować wpis (post). Zablokowane wpisy nie mogą otrzymywać głosów, ani być w żaden sposób zmieniane.
  • Moderator widzi wszystkie dane w systemie - w tym głosy oraz informacje o profilach użytkowników.
  • Moderator może zawiesić użytkownika oraz usunąć, jeśli jest to konieczne.
  • Moderator może wykonywać czynności administracyjne typu łączenie pytań, czy masowe retagowanie.

Z dnia na dzień przybywa serwisowi aktywnych użytkowników. Co za tym idzie, coraz częściej zdarzają się sytuacje, które wymagają interwencji moderatora. Postanowiliśmy zatem mianować 5 wybranych przez nas użytkowników moderatorami. Funkcje te przypadły następującym osobom:

Gutkowski plakietka
Łukasik plakietka
Kuczyński plakietka
Aniserowicz plakietka
Gil plakietka

Jeśli jesteś moderatorem, bądź posiadasz uprawnienia zbliżone do takich, jakie ma moderator, to czego od Ciebie oczekujemy?

  1. Jako moderator, Twoje czyny reprezentują nasz serwis - prosimy zachowuj się stosownie. Znajdujesz się na stanowisku, które obdarzone jest dużym zaufaniem.
  2. Twoim zadaniem jest prowadzenie społeczności z delikatną - ale pewną - interwencją. Szanuj członków społeczności. W swoich czynach utrzymuj sprawiedliwość oraz spójność.
  3. Utrzymuj dyskusje w temacie, poprzez zamykanie oraz usuwanie wpisów, które są nie na temat.
  4. Regularnie rozprawiaj się z oflagowanymi wpisami.
  5. W przypadku ostrych konfliktów, komunikuj się bezpośrednio z użytkownikami poprzez e-mail, aby pomóc je wyjaśniać.

Od moderatora wymagamy najmniejszej możliwej ingerencji. devPytania są tak skonstruowane, aby większość typowych "moderacyjnych" akcji było wykonywane przez społeczność.

Wszystkim użytkownikom serwisu serdecznie dziękujemy za aktywność. Mamy nadzieję, iż sposób w jaki tworzona jest społeczność devPytania pozytywnie wpłynie na rozwój każdego, kto do niej należy.


Zespół devMedia.pl

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

Nie ma czegoś takiego jak najszybszy kod

Oryginalny post: There Ain't No Such Thing as the Fastest Code

Autor: Jeff Atwood

Uradowałem się, gdy zobaczyłem, że James Hague wybrał książkę The Zen of Assembly Language Programming jako jedną z pięciu, godnych zapamiętania książek o programowaniu. Całkowicie się z tym zgadzam. Nawet jeśli podczas swojej zawodowej kariery nie planujesz nawet liznąć asemblera, to ta książka jest i tak fantastyczna oraz całkowicie godna polecenia. Byłem zwykłym programistą Visual Basica w momencie, gdy natrafiłem na tę książkę (razem z The Zen of Code Optimization), zacząłem czytać ją dla zabawy i ledwie mogłem się od niej oderwać. Jest tak dobra.

Abrash nie tylko jest wpływową postacią wśród inżynierów oprogramowania, ale również jednym z najlepszych technicznych pisarzy, jakiego jesteś w stanie znaleźć. To dlatego jest on jednym z moich programistycznych bohaterów, zaraz obok Steve'a McConnell'a.

Jego książka Graphics Programming Black Book jest świetna w podobny sposób i pokrywa tak rozległe tematy, że tytuł staje się trochę niewłaściwy. Najlepsze jest to, że dzięki uprzejmości Dr. Dobb's jest ona dostępna w sieci, więc można ją wypróbować samemu.

Michael Abrash Graphics Programming Black Book

Wiem, co sobie myślisz. "Ta książka jest o grafice. I o asemblerze. Dodatkowo, jest z 1996 roku, co w komputerowych latach oznaczałoby 1928. Jako programista, nie jestem nią zainteresowany." Przyznaj to. Tak właśnie. Ale wiesz, co zamierzasz zrobić? Zamierzasz i tak ją przeklikać, i trochę poczytać. Tak jak na studiach, tematyka zajęć nie jest istotna, jeśli wykładowca jest znakomitym nauczycielem. A dokładnie takim nauczycielem jest Abrash.

Abrash jest światowej sławy programistą oraz pisarzem technicznym, ale również nie wstydzi się wyjaśniać zagrożenia oraz niebezpieczeństwa związane z naszą profesją, włączając w to największy problem ze wszystkich — ten, który siedzi za klawiaturą. Pozwól mi, iż zilustruję to za pomocą jednego z moich ulubionych paragrafów Abrasha, z 16 rozdziału książki Graphics Programming Black Book.

Nie tak dawno temu, Terje Mathisen, którego przedstawiłem wcześniej w książce, napisał bardzo szybki program zliczający wyrazy, a następnie umieścił go w serwisie BIX. Kiedy mówię, że był szybki, to mam na myśli szybki; ten kod był rewelacyjnie zoptymalizowany. Mówimy tu o kodzie najwyższej jakości.

Kiedy temat optymalizacji został poruszony na jednej z konferencji BIX, to został również wspomniany program Terje'a, i ogłosił on następującą wiadomość: "Rzucam wyzwanie społeczności BIX (a w szczególności mabrashowi!), abyście znacznie przyspieszyli mój program. Wynik w wysokości 5% uznaję za dobry." Oczywistym wnioskiem było to, że "ten kod był tak szybki, jak to tylko możliwe."

Oczywiście nie był; nie ma czegoś takiego jak najszybszy kod.

[sztuczki asemblera i użyteczne podejścia optymalizacyjne w skrócie — zobacz PDFa, jeśli chcesz więcej]

Największą barierą optymalizacyjną jaką napotkał Terje było to, iż myślał, że posiadał najszybszy możliwy kod. Kiedy już otworzył się na możliwość, że istnieją szybsze podejścia, i spojrzał poza to konkretne podejście, które tak ostrożnie optymalizował, to był w stanie stworzyć kod, który był o wiele szybszy. Zauważ nieodpowiedniość chęci Terje'a, aby uznać 5% przyspieszenie za znaczące w świetle jego późniejszego niemal dwukrotnego zwiększenia wydajności.

W tym samym rozdziale, Pan Abrash nawiązuje do podobnej anegdoty opartej na programie do zliczania słów. Był on opublikowany jako wyzwanie w jego sekcji "Pushing the Envelope":

Wyzwanie zostało zapoczątkowane przez artykuł dotyczący liczenia wyrazów w dokumencie, napisany przez Davida Gerrolda; David przedstawił też w międzyczasie kila całkiem interesujących problemów optymalizacyjnych. Zaprogramował wszystko w Pascalu zaznaczając przy tym, że wersja w asemblerze prawdopodobnie byłaby szybsza, ale jego wersja pascalowa działała poprawnie i była wystarczająco szybka dla niego.

Jednakże nie była wystarczająco szybka dla mnie. Logicznym punktem startowym do przyspieszania programu do liczenia wyrazów wydawał się być oryginalny kod pascalowy Davida, ale jako iż lepiej się czuję w C, więc stworzyłem luźną aproksymację programu Davida przetłumaczoną na C.

Mike kontynuował to, w czym jest najlepszy — zoptymalizował program do liczenia wyrazów w kodzie asemblera i wyjaśnił przy okazji w sposób opanowany i wysoce elokwentny. Efekty jego pracy są następujące:

konwersja do C 4.6 sekundy
konwersja do C oraz asemblera 2.4 sekundy
konwersja do C oraz asemblera z tabelą podglądu 1.6 sekundy

Następnie opublikował on swój program jako wyzwanie dla czytelników PC Techniques — czy ten program do zliczania słów napisany w zoptymalizowanym asemblerze, autorstwa uznanego przez branżę eksperta w dziedzinie optymalizacji asemblera, może być uczyniony jeszcze szybszym? Cóż, podejrzewam, iż możesz zgadnąć co nastąpiło potem.

Tak więc jak plasowali się uczestnicy tego konkretnego wyzwania? Więcej niż jeden twierdził, iż trzykrotnie przyspieszył mój asemblerowy kod zliczający wyrazy. Biorąc pod uwagę trzykrotne przyspieszenie w stosunku do kodu C, które zrealizowałem, to mamy do czynienia niemal z przyspieszeniem o rząd wielkości. Oczywiście masz prawo do swojej opinii, ale ja uważam, że rząd wielkości jest znaczący.

Prawdę mówiąc, nie oczekiwałem trzykrotnego przyspieszenia; dwukrotne, to było to, co miałem na myśli. Co z kolei pokazuje, iż każdy kod może zostać przyspieszony bardziej, niż tego oczekujesz, jeśli odpowiednio długo i z odpowiednio wielu perspektyw się nad nim zastanowisz.

Jak to powiedział Mike, nie ma czegoś takiego, jak najszybszy kod. Jeśli uważasz, że jest, to prawdopodobnie Ty jesteś barierą stojącą na drodze ku lepszej wydajności, a nie kod.

Data publikacji oryginału: 19 lutego, 2008

Related Posts with Thumbnails