NAME

Nazwa aplikacji -- jednowierszowy opis przeznaczenia aplikacji.


VERSION

Na początku dokumentacja zawiera jedynie tekst:

This documentation refers to 'nazwa aplikacji' version 0.1


USAGE

  # krótki, działający przykład zastosowania aplikacji
        
  # wielu użytkowników zakończy lekturę na tej sekcji
  # zatem powinna ona być jak najbardziej pouczająca

Czasami ten rozdział nazywa się synopsis:


SYNOPSIS

  # krótki, działający przykład zastosowania aplikacji


REQUIRED ARGUMENTS

Pełna lista argumentów, które muszą występować w wierszu polecenia podczas uruchamiania aplikacji, wraz z ich przeznaczeniem, miejscem, w którym należy je umieścić (na przykład znaczniki muszą występować przed nazwami plików lub po nich), oraz interakcjami między poszczególnymi argumentami i opcjami (na przykład wzajemnym wykluczaniem, wymaganymi kombinacjami, itp.)

Jeżeli wszystkie argumenty aplikacji są opcjonalne, można tę sekcję pominąć.


OPTIONS

Pełna lista opcji, z którymi można uruchamiać aplikację, wraz z ich przeznaczeniem, ograniczeniami i interakcjami.

Jeżeli aplikacja nie ma żadnych opcji, można tę sekcję pominąć.


DESCRIPTION

Pełen opis aplikacji i jej funkcji. Może zawierać podsekcje (tzn. =head2, =head3, itp.), na przykład takie:

Typical usage

Special usage cases

Working in chrooted environment


EXAMPLES

Wiele osób lepiej uczy się na przykładach niż na wyjaśnieniach, a większość uczy się najlepiej na ich kombinacji. Katalog /demo z dobrze udokumentowanymi przykładami to świetny pomysł, ale nie wszyscy użytkownicy mają dostęp do oryginalnej dystrybucji, a administratorzy rzadko instalują przykłady. Dołączenie kilku przykładów do samej dokumentacji może znacznie ułatwić naukę programu.


COMMON USAGE MISTAKES

Ta sekcja w rzeczywistości mogłaby się nazywać ``często niezadawane pytania''. Niezależnie od rodzaju programu może się zdarzyć, że użytkownicy źle zrozumieją jakieś pojęcie albo będą błędnie używać niektórych komponentów. Zwracając uwagę na często popełniane błędy, wyjaśniając nieporozumienia i wskazując prawidłowe możliwości, możemy znacznie ograniczyć ilość bezproduktywnej korespondencji. Sam perl oferuje tego rodzaju dokumentację w postaci strony perltrap.


DIAGNOSTICS

Lista błędów i komunikatów diagnostycznych generowanych przez aplikację (nawet takich, które ``nigdy się nie zdarzą''), z pełnym wyjaśnieniem każdego problemu, możliwych przyczyn i sugerowanych rozwiązań. Jeśli aplikacja generuje kody wyjściowe (na przykład w systemie Unix), należy wymienić kody związane z każdym błędem.


CONFIGURATION AND ENVIRONMENT

Pełne wyjaśnienie systemu konfiguracji używanego przez aplikację, w tym nazwy i lokalizacje plików konfiguracyjnych oraz znaczenie zmiennych środowiskowych albo właściwości. Należy też opisać składnię języka konfiguracyjnego.


DEPENDENCIES

Wymieniamy i opisujemy zależności, z jakich korzysta aplikacja. Mogą to być np. jakieś nietypowe moduły perla lub dodatkowe biblioteki zainstalowane w systemie. Należy opisać ich wersje i zaznaczyć, czy pochodzą z dystrybucji perla czy wymagają oddzielnej instalacji.


INCOMPATIBILITIES

Opisujemy możliwe niekompatybilności z systemem operacyjnym, środowiskiem lub pozostałym oprogramowaniem lub sprzętem. Niezgodności mogą wynikać z konfliktów nazw, pokrywania się funkcjonalności zastosowanych różnych bibliotek, współzawodnictwa o zasoby systemowe albo wewnętrznych ograniczeń perla.


BUGS AND LIMITATIONS

Lista znanych problemów oraz informacja o tym, czy zostaną poprawione w następnej wersji. Opisujemy wszystkie znane błędy, które istnieją w aplikacji i nie są jeszcze poprawione. Opisujemy także ograniczenia, np. dotyczące pracy z bazą danych, pojemnością pamięci, ilością danych, jakie aplikacja może przetwarzać, itp.

Pierwsza wersja dokumentacji zawiera zwykle tekst:

There are no known bugs in this application. Please report problems to {osoba konserwująca kod} ({adres mailowy}). Patches are welcome.


FREQUENTLY ASKED QUESTIONS

Dołączenie listy odpowiedzi na często zadawane pytania może wydawać się dodatkowym obciążeniem (zwłaszcza wtedy, gdy chodzi o jej aktualizowanie), ale w rzeczywistości często pozwala zaoszczędzić czas. Pytania są zwykle przesyłane pocztą elektroniczną, a większość z nas i bez tego odbiera za dużo poczty. Jeśli to samo pytanie wielokrotnie pojawia sie wiadomościach email, w grupie dyskusyjnej albo na stronie WWW, warto na nie odpowiedzieć w dokumentacji. Zmniejszy to liczbę osób pytających wciąż o to samo zagadnienie, a nawet jeżeli ktoś zapyta, będzie można odesłać go do podręcznika w myśl zasady RTFM*.


AUTHOR

Piszemy kto zrobił aplikację i wymieniamy wszystkich znanych nam autorów mających wkład w jej powstanie. Jest to miejsce na pozostanienie kontaktów do siebie i umożliwienie użytkownikom wysłania raportów i informacji zwrotnej o działaniu aplikacji.


LICENCE AND COPYRIGHT

Copyright (c) {rok} {posiadacz praw autorskich} ({adres kontaktowy}). All rights reserved.

Dalej następuje odpowiednia licencja. W przypadku kodu perla często jest to tekst:

This application is free software; you can redistribute it and/or modify it under the same terms as perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


(DISCLAIMER OF) WARRANTY

Ta sekcja ma duże znaczenie w oprogramowaniu, które prawdopodobnie będzie używane poza organizacją zatrudniającą programistę. Powinna być oddzielona od sekcji ``Copyright and License'' i napisana przez kompetentnego prawnika (żebyśmy mieli kogo pozwać do sądu, jeżeli ktoś pozwie nas). Ci, którzy nie pracują w korporacji i nie mają do dyspozycji radców prawnych, mogą korzystać z klauzul 11 i 12 Licencji Publicznej GNU (http://www.gnu.org/copyleft/gpl.html).


SEE ALSO

Często istnieją inne moduły lub aplikacje, których można używać zamiast opisywanej, inna dokumentacja, która może się przydać użytkownikom, albo artykuły i książki wyjaśniające zasady funkcjonowania aplikacji. Zamieszczenie ich w tej sekcji pozwala użytkownikom lepiej zrozumieć oprogramowanie i rozwiązać problemy bez pisania do autora.


ACKNOWLEDGEMENTS

Zawsze wypada podziękować za pomoc w pisaniu i ulepszaniu oprogramowania. Jednakże wyrażenie wdzięczności jest nie tylko uprzejme, ale również leży w interesie programisty. Użytkownicy często przysyłają raporty o błędach, ale byłoby znacznie lepiej, gdyby dołączyli do nich działające poprawki. Pobliczne podziękowanie za nadesłane wcześniej poprawki przypomina użytkownikom, że ich zaangażowanie jest zawsze mile widziane.


FOOTNOTES

RTFM - ang. Read the funny manual (poczytaj fajny podręcznik), a w innej wersji Read the fucking manual (poczytaj pieprzony podręcznik) - akronim sieciowy oznaczający odesłanie do dokumentacji osobę, która zadaje oczywiste pytania, na które odpowiedzi są łatwo dostępne. Nie zaleca się nadużywania tego zwrotu gdyż uznawany jest on w pewnych kręgach za ofensywny i obraźliwy.