5979906039

W

wiejcie p

WMffle powieści to te. które są nieco niejasne, tak że czytelnik me może być do końca pewien.

co one znaczą.

2.5.5. Dokumentacja to nie powieść

Dobry styl pisarski ma pewne cechy, które nie są właściwe w odniesieniu do dokumentowania złożonego procesu tworzenia oprogramowania. Poniżej przedstawiamy trzy rzeczy, które większość z nas lubi w literaturze, oraz powody, dla których powinno się ich unikać w dokumentacji:

Pomysłowość. Najlepsze książki pochłaniają całą naszą inteligencję i wyobraźnię i jeśli jest to zbyt łatwe, może być nudne. W dokumentacji najważniejsza powinna być jednoznaczność. Jeśli pomysłowa prezentacja straci nawet najbardziej wytrwałego czytelnika, to dokument nie spełni swojego celu.

Zróżnicowana terminologia. Nudne jest odwoływanie się ciągle do czegoś, stosując dokładnie to samo słowo. Pisarze nauczyli się więc unikać powtórzeń. W dokumentacji czytelnik jest bardziej zainteresowany dokładnym zrozumieniem tematu niż różnorodnością. Jeśli jest to „garg”, mów na to „garg” a nie inaczej, nawet jeśli słowo „blorg” jest synonimem.

Rozproszenie pojęć. Powieści zwykle nie mają skorowidza, a jeśli mają, to każdy zapis będzie miał odnośniki do wielu stron, a informacje będą rozrzucone po całej książce. W dokumentacji jest dokładnie na odwrót: każde pojęcie jest zdefiniowane dokładnie w jednym miejscu. Trudno jest czytać dokumentację, ale łatwo jest w niej coś znaleźć.

Większość zasad dotyczących dobrego pisania stosuje się do dokumentacji. W szczególności ważne jest stosowanie konstrukcji równoległych, właściwe użycie paragrafów, trzymanie się tematu itd.