Ogólne wskazówki odno nie tworzenia dokumentacji do programu

Ogólne wskazówki odnośnie tworzenia dokumentacji do programu napisanego
w ramach zajęć projektowych.
1. Dokumentacja powinna być oddana wyłącznie w formie elektronicznej, w postaci
pliku w formacie PDF.
2. Dokumentacja do projektu musi składać się co najmniej z dwóch części:
instrukcji użytkownika i dokumentacji technicznej.
3. Instrukcja użytkownika powinna zawierać zwięzły, ale dokładny i zrozumiały opis
użytkowania programu począwszy od etapu kompilacji (co jest potrzebne do
skompilowania programu, czy wymagane jest ustawienie specjalnych opcji
kompilator, itd.) po zakończenia działania programu. Opis powinien również
dokładnie wyjaśniać do czego program służy (można też stworzyć rodzaj
przewodnika po programie).
4. Dokumentacja techniczna zawiera opis kodu. Powinien on być zgodny z podziałem
programu na moduły. W opisie należy wyjaśnić rolę ważniejszych typów danych
określonych przez programistę, zmiennych i stałych. Należy wyjaśnić funkcję
i zasadę działania każdego podprogramu. W przypadku małych podprogramów
wystarczy zwięzły opis słowny, natomiast opisy dużych podprogramów powinny
zawierać dodatkowe elementy objaśniające ich działanie, np. schematy blokowe.
5. Schematy blokowe powinny być wykonane czytelnie i estetycznie. Wewnątrz
bloków należy umieszczać opisy słowne reprezentowanych przez nie operacji.
Zapisów symbolicznych należy używać jedynie w przypadku bardzo prosty
operacji (np. przypisanie) lub wzorów matematycznych. W ostatnim przypadku
w opisie słownym należy podać objaśnienie wzoru. Schematy blokowe można
budować metodą od najbardziej ogólnego do najbardziej szczegółowego
umieszczając wewnątrz poszczególnych bloków odnośniki do innych schematów,
jeśli jest to konieczne. Dobrze narysowany schemat blokowy powinien mieścić się
na jednej stronie. Osoby piszące program z użyciem techniki obiektowej mogą
w dokumentacji umieścić proste schematy, podobne do tych jakie obowiązują
w języku UML.
6. W końcowej części dokumentacji należy umieścić bibliografię, czyli spis literatury,
ewentualnie innych źródeł informacji wykorzystanych podczas pisania programu.
W treści dokumentacji należy umieścić odnośniki do tych źródeł, np. w postaci
numeru w spisie umieszczonego w nawiasach kwadratowych.
7. Dokumentacja techniczna nie powinna zawierać kodu, ale może zawierać
odnośniki do niego w postaci nazwy pliku, gdzie ten kod występuje i numerów
wierszy kodu, których opis dotyczy.
8. Dokumentacja nie może zawierać błędów ortograficznych i powinna być czytelna
oraz zrozumiała !!!
9. Należy zadbać o to aby wyeliminować w treści dokumentacji błędy językowe.