Pisanie świetnej dokumentacji: potrzebujesz redaktora

Listopad 12, 2009

Część serii Pisanie świetnej dokumentacji.

To ja powinienem być tym ekspertem od pisania, nie? Jak to możliwe w takim razie, że moje poprzednie artykuły miały tak wiele błędów?

To proste: mój blog nie ma redaktora.

To typowe dla bloga, ale niestety także bardzo powszechne dla dokumentacji open source: znaczna większość dokumentacji technicznej nie zachodzi dalej niż poza szkic.

Wszyscy dobrzy pisarze mają swój wstydliwy sekret: nie są naprawdę tak dobrzy w pisaniu. Ich redaktorzy to zapewniają. Nie ma znaczenia, jak dobrze opanowałeś język; nikt, nawet gramatyczni wyjadacze, nie robią tego dobrze za pierwszym razem.

Jeśli naprawdę chcesz stworzyć świetną dokumentację, musisz poprosić o jej zredagowanie.

Wskazówki redaktorskie

Daleko mi do redaktora-eksperta, ale - zgodnie z wielką tradycją otwartego oprogramowania - "potrzebujemy..." zwykle tłumaczy się do "zgłaszam się do..." i często kończę jako taki redaktor.

Jeśli masz możliwość popracować z dobrym redaktorem, to polecam spróbować - to fantastyczne. Jednym z najlepszych elementów pisania książki jest nauka płynąca z redagowania.

Niestety, zwykle większość inicjatyw nie może skorzystać z luksusu posiadania prawdziwego redaktora. Kilka rad dla Ciebie, jeśli - także - zostaniesz postawiony w tej roli:

  • Nie redaguj bez pozwolenia.

    Pamiętaj: ludzie piszący dokumentację online niemal zawsze są ochotnikami i często nie mogą czerpać korzyści z posiadania formalnej edukacji w piśmiennictwie. Prawdopodobnie są zainteresowani rozwojem w tej materii, ale zapytaj o pozwolenie zanim się zagłębisz w tekście.

    Trudno o sposób na to, by stwierdzić głośno, że ktoś zrobił błąd bez brzmienia jak palant, więc upewnij się, że Twoja krytyka jest pożądana. Przyczepianie się do czyjejś gramatyki i stylu tylko dlatego, że myślisz, że jesteś jakiegoś rodzaju ekspertem jest po prostu niegrzeczne.

  • Bądź przygotowany. Upewnij się, że masz swój przewodnik po stylu, cały materiał referencyjny i dobry słownik (także synonimów). Niemal zawsze narastają pytania w trakcie pracy; bądź przygotowany, by na nie odpowiedzieć.

  • Unikaj redagowania własnej pracy (zerknij jednak na sekcję poniżej, jeśli musisz).

    Jest niemalże niemożliwym by z sukcesem redagować własną pracę. Gdy czytasz coś, co napisałeś samodzielnie wiesz, co chciałeś napisać, więc łatwo pominąć literówki czy brakujące słowa.

    Ja także redaguję to, co jest opublikowane na tym blogu, ale nie mógłbyś tego stwierdzić po ilości zawstydzających błędów. Byłoby znacznie lepiej, gdybym sam nie redagował własnej pracy.

  • Redaguj na papierze.

    Jak rozważaliśmy wczoraj, materiały online czytamy zupełnie inaczej niż drukowane. Tekst na ekranie skłania do prześlizgiwania się, więc omijamy błędy, które w druku byłyby oczywiste.

    Redaguję czerwonym tuszem, rzecz jasna.

  • Czytam powoli. Nie ma sensu przelatywać po tekście tak szybko, jak to możliwe. W zasadzie chodzi o coś zupełnie odwrotnego. Powinieneś celować w to, by nad każdym słowem spędzić tak dużo czasu, jak to możliwe.

    W rzeczywistości czytam tekst "na głos". Redaguję zwykle w miejscach publicznych - kawiarniach czy bibliotekach - gdzie prawdziwe czytanie na głos mogłoby być dziwne, ale wokalizuję i cicho poruszam wargami tak, jakbym czytał każde słowo.

    Szczęśliwie mieszkam w miasteczku, w którym ktoś mówiący do siebie samego na końcu biblioteki jest czymś całkiem normalnym, więc nikt nie zauważa kolesia szepczącego do siebie w rogu.

  • Przejrzyj tekst kilka(trzy-)krotnie. Wygląda na to, że znajduję około 90% błędów za każdym przejrzeniem. Prawie nigdy nie zdarza się, bym nie znalazł czegoś. Dwa przeglądy to u mnie standard; trzeci jest poświęcony na dodatkowe polerowanie.

Ponad wszystko: bądź spójny. Dla pisarza niespójni redaktorzy są rozwścieczający. Jeśli masz zamiar zająć się redagowaniem, musisz redagować zawsze w stronę tego samego stylu.

Samodzielne redagowanie tekstu

W świecie open source istnieje silny efekt ogona, więc większość projektów kończy jako produkt jednej osoby. Zatem i dokumentacja jest produktem pochodzącym od jednej osoby. Można do tego dodać, że w wielu większych społecznościach dokumentacja jest zaniedbywana i powstaje w wyniku wysiłku jednej osoby.

W praktyce więc "Twój redaktor" kończy się na "Ty". W takim wypadku przyda się kilka rad na temat skutecznych technik samodzielnego redagowania:

  • Unikaj redagowania i pisania jednocześnie. Nic nie zabija "flow" bardziej, niż ciągłe krytykowanie siebie samego. Wyłącz sprawdzanie pisowni, wyłącz sprawdzanie gramatyki i, co najważniejsze, spróbuj wyłączyć tę krytykancką część Twojego umysłu do czasu rozpoczęcia redagowania.

    To jest jeden z głównych powodów, dla których ląduję w kawiarni czy bibliotece, gdy redaguję: piszę coś, drukuję i idę gdzieś indziej, by móc to poprawić. Uczę się myślenia o redagowaniu jako o zupełnie oddzielnej roli, w którą wcielam się w innym miejscu, niż piszę.

  • Daj sobie trochę czasu. Jeśli pozwolisz, by trochę czasu upłynęło między pisaniem i redagowaniem, to to, co napisałeś, odrobinę wyblaknie w Twojej pamięci i zacznie wyglądać nieco mniej znajomo. Będzie mniej prawdopodobnym byś "wiedział" co napisałeś, i nieco bardziej prawdopodobnym byś zauważył błędy.

  • Zmień szerokość marginesu. To strasznie głupi trik, ale kurczę działa. Po prostu zmień szerokość kolumny lub marginesy w swoim edytorze, a gdy Twój tekst się przeorganizuje zacznie wyglądać nieco inaczej. Dla mnie ta niewielka różnica jest wystarczająca, by obudzić mój mózg i odnaleźć błędy natychmiast po reorganizacji.

Niestety, żadna liczba trików nie pomoże Ci naprawdę, jeśli musisz redagować tekst samodzielnie. Zawsze pozostaną jakieś błędy. Ostatecznie jednak jakaś dokumentacja zawsze pobije brak dokumentacji.

Daj z siebie wszystko... i bezwarunkowo naciśnij przycisk "publikuj"!

3 komentarze:

nietaki pisze...

O ile jeszcze mam wątpliwości, czy "editor" w tym artykule należałoby przetłumaczyć na "redaktor" zamiast "edytor", to wszystkie wystąpienia czasownika "edytować" należałoby zastąpić "redagować". Jest to dosłowne, rdzennie polskie tłumaczenie, które daje pojęcie o jakiej czynności mówimy...

Karol Stosiek pisze...

Dziękuję bardzo za uwagę; wprowadziłem stosowne poprawki.

noisy pisze...

Jak widać, osoba chcąca dzielić się swoją wiedzą ma naprawdę wiele obszarów do opanowania. Generalnie umiejętność przelewania swoich myśli na papier, obycie z wystąpieniami publicznymi i tremą.. Okazuje się, że i redagowanie ma tutaj kolosalne znaczenie...

Może to jednak lepiej, że to wszystko wymaga tyle zachodu... człowiek ma motywacje, do pracy nad własnym rozwojem! :)

Prześlij komentarz

Related Posts with Thumbnails