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

8 komentarze:

MichalBe pisze...

"tą szkołę" czy "tę szkołę" ?

batman pisze...

Autor zapomniał o jednej bardzo ważnej kwestii, mianowicie o... czytaniu. I nie mam tutaj na myśli różnych dokumentacji, czy prasy codziennej. Chodzi mi o książki nietechniczne. Taka lektura, nawet w najprostszej formie, jest o wiele lepsza niż setki napisanych dokumentów.

Anonimowy pisze...

@MichalBe
szkoła -> ta szkoła -> tą szkołę

@batman
"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."
Wiec jest w artykule o czytaniu. A skad Ci przyszlo do glowy, ze maja to byc tylko ksiazki techniczne?

batman pisze...

Jest ale za mało. To tylko wzmianka, która nie mówi wprost, że czytanie pomoże w pisaniu.
Książki techniczne już sam dopisałem, bazując na swoich doświadczeniach oraz obserwacji środowiska.

Marek Stój pisze...

@Anonim

kogo co? tę szkołę
z kim? z czym? z tą szkołą

Karol Stosiek pisze...

Dziękuję za poprawki językowe.

Anonimowy pisze...

Nie "nie mniej jednak", ale "niemniej jednak". Dodatkowo w polskim nie wstawiamy znaków interpunkcyjnych wewnątrz cudzysłowów. Pozdrawiam.

Karol Stosiek pisze...

Dziękuję za uwagę. W niektórych z cudzysłowów znaki interpunkcyjne zostały zachowane ze względu na intencje autora wpisu.

Prześlij komentarz

Related Posts with Thumbnails