Porady dla piszących dokumentacje PLD

Te pakiety będą nam potrzebne do pracy przy tworzeniu dokumentacji:

Na pewno jakiś edytor tekstowy. Proponuje VIM™, gdyż ma kolorowanie i robi wcięcia ale oczywiście możemy użyć swojego ulubionego edytora. Dla VIMa możemy sobie ściągnąć .vimrc, skopiować do domowego katalogu (pamiętając o ustawieniu odpowiednich praw) i po uruchomieniu VIMa w trybie edycji mamy dodatkowo szybką obsługę tagów docboka. Przykładowo po podaniu sekwencji ,pp stworzą nam się tagi para, a po poleceniu ,cm1 lewy tag command - a ,cm2 zamknie nam tag command. Przeglądając i edytująć w/w plik konfiguracyjny możemy bardzo łatwo przystosować pracę w VIMie do naszych upodobań.

Można także zajrzeć na stronę dpawsona. Do tego opisu można dodać jeszcze program conglomerate™ pod KDE™ (chociaż jeszcze nie nadaje się on do poważnej pracy - często oopsuje)

Gdy już jesteśmy przygotowani programowo i psychicznie proponuje podróż na strone Docbooka. Mimo że po angielsku to sekcja Read The Book jest na tyle zwięzła i czytelna że rozjaśni wiele w naszych głowach... a jak nie to standardowo - lista PLD-doc, IRC i google :)

Dla ułatwienia pracy w SVN skopiowane zostały szablony dokumentów docbooka dla języka angielskiego i polskiego (w katalogu template). Kopiujemy odpowiedni szablon do pliku, który chcemy stworzyć pamiętając o przyjętej notacji nazewnictwa np:

język_dział__temat.docb

czyli przykładowo: "pl_instalacja__instalacja_pld.docb". Należy zwrócić uwagę na podwójny __ po dziale, co ułatwi później obróbkę pliku. Umówmy się także, że w nazwach nie używamy wielkich liter. Zwróćmy także uwagę na podział opisany niżej.

Praca nad dokumentami jest zmodularyzowana. Oznacza to, że istnieje dokument główny, który zawiera odpowiednie zapisy dotyczące zewnętrznych plików (w template opisuje to plik "pl_template__master.docb") i pliki na których pracujemy - są to rozdziały (*.chp) i sekcje (*.sec) - przykład plików podrzędnych mamy w katalogach "template/pl_template/".

Po edycji dokumentów należy bezwzględnie dokonać sprawdzenia (walidacji) - Dokonujemy tego poleceniem:

xmllint --valid --noout (przykładowo: xmllint --valid --noout pl_test.docb)

W przypadku korzystania z modularnie zbudowanych dokumentów, walidacji dokonujemy tylko na głównym dokumencie. Przykładowo w naszym katalogu ./book jest to plik pl_book__master.docb

$ xmllint --valid --noout pl_book__master.docb

Oczywiście wszystkie błędy składniowe, które podczas sprawdzenia zostaną wyświetlone, musimy poprawić.

Interesuje nas pewnie wizualizacja tego co robimy. Możemy skorzystać ze skryptu docbook2html z pakietu docbook-utils, który z poprawnego docbooka zbuduje nam strony html... chyba nie trzeba już tłumaczyć co potem? Przydatna może być tutaj opcja '-u', która z podanego dokumentu docbook stworzy pojedyńczy plik HTML (domyślnie każdy rozdział ląduje w innym pliku).

Gdy już jesteśmy pewni swojego dzieła udostępniamy go SVN. A potem poprawiamy, poprawiamy i poprawiamy :)

Dokumentację piszemy po polsku. Co to znaczy? Przede wszystkim unikamy wszelkich kolokwializmów, nie piszemy, że "jeśli nie działa, to dupa". Nie piszemy, że "wszystko bangla" albo że "coś nie hula". Nie piszemy jej dla siebie, będą czytać ją inni ludzie i oczekują od niej konkretów, a nie niezwykle elokwentnego i wysublimowanego poczucia humoru.

Unikamy komentarzy odautorskich w stylu "ale ja bym do tego użył ..." albo "mimo wszystko, wolę ...". Nie piszemy też, że "to mój ulubiony pakiet".

W miarę możliwości stawiamy znaki przestankowe zgodnie z zasadami polskiej interpunkcji. Przed wysłaniem własne dokumenty przepuszczamy przez ispella.

W długich paragrafach łamiemy wiersze. Nie każdy ma terminal na cały ekran w 1600x1200. Dużo łatwiej jest wtedy wyłapać błędy i znacznie ułatwia późniejsze tłumaczenie dokumentu.

Screeny prezentujące polecenia konsekwentnie zaczynamy od stosownego znaku zachęty. Dolar oznacza polecenia niewymagające praw roota, hash polecenia wymagające takich uprawnień. Przy opisie poleceń ogólnego użytku (które same z siebie nie wymagają żadnych specjalnych uprawnień) wybieramy przykłady również niewymagające uprawnień. Np. nie jest dobrym pomysłem pokazanie jako przykład zastosowania polecenia cp konstrukcji takiej jak poniżej:

# cp /etc/modules.conf /etc/modprobe.conf

Screeny prezentujemy bez zbędnych rzeczy, np. nie wklejamy prompta, jeśli nie jest on przedmiotem screena. To samo tyczy się końcowego znaku zachęty. Nie wklejamy więc na końcu screena pustego znaku "#".

Nazwy własne pakietów i programów otaczamy tagami "productname", np.:

Do tego celu posłuży nam program poldek™

Nazwy poleceń otaczamy tagami "command":

Aby go uruchomić, wpisz po prostu poldek.

Zauważ różnicę kontekstu, w którym występuje słowo "poldek" w obu powyższych przykładach.

Na samym początku musimy pobrać tzw. repozytorium. Wydajemy taką komendę:

svn co http://svn.pld-linux.org/svn/PLD-doc PLD-doc

Pojawi się monit o wpisanie hasła. Logujemy się i po chwili powiniśmy mieć ściągnięte repozytorium pld-doc z serwera SVN.

Aby założyć katalog piszemy:

svn mkdir nasz_katalog

Do katalogu który założyliśmy przed chwilą możemy kopiować pliki w taki sam sposób jak robimy to podczas normalnej pracy. O czym należy pamiętać. Jeżeli chcemy aby katalog jak również pliki które do niego skopiowaliśmy stały się dostępne dla innych użytkowników systemu svn, musimy wykonać następujące czynności. Po pierwsze musimy jak gdyby 'powiedzieć' systemowi które pliki będziemy mu wysyłać. Wykonujemy:

svn add plik1 plik2 plik[n]

a następnie udostępniamy swoje zmiany innym, wykonując tzw. commita.

svn ci -m "- krotki opis co zrobiliśmy"

Zostaniemy poproszeni o wpisanie hasła. Po udanej autoryzacji nasze zmiany już są dostępne dla innych.

Uwaga! Przed commitem należy wykonać trzy czynności:

Przed zmianami w naszym lokalnym repozytorium SVN należy dokonać aktualizacji. Wszelkie modyfikacje jakie zostały poczynione przez innych zostaną wczytane i zmniejszy się prawdopodobieństwo wystąpienia konfliktów, które mogą wystąpić gdy trwają prace przy tych samych fragmentach dokumentacji.

cd ~/pld-doc 
svn up