„Program jest tak dobry jak jego dokumentacja”

Cel

wyjaśnienie działania programu. Różnią się w zależności czy jest to program o celach edukacyjnych czy komercyjny.

Rodzaje

ręczna
- komentarze w kodzie źródłowym
- ASCII art ^[1]
- pliki tekstowe
  - readme
    - markdown
    - asciidoc
    - DITA
automatyczna
- doxygen
- cldoc - clang based documentation generator for C and C++

typy dokumentacji produktu ( programu)

Instrukcje szkoleniowe ( ang. Training manuals)
Instrukcje użytkownika ( ang. User manuals)
Instrukcje instalacji ( ang. Installation guides)
Poradniki rozwiązywania problemów ( ang. Troubleshooting guides)
Instrukcje szybkiego startu dla noiecierpliwych ( ang. Quickstart guides)
Dokumentacja API ( ang. API documentation)
Poradniki ( ang. Tutorials)

Doxygen

Sprawdzamy instalację: ^[2]

 file $(which doxygen)
 ls -l $(which doxygen)

Opis programu ( specyfikacja)

Specyfikacja programu opisuje jego cechy. Pozwala to na lepsze zrozumienie programu. Nie musimy wypełniać wszystkich cech, ale im więcej tym lepiej.

Docelowa platforma sprzętowa ( ang. Target Platform ):

Operating System ( Linux, Windows, Mac
Architecture (
Distribution ( Ubuntu, Debian,
- Version

Specyfikacja programu:

język mówiony (polski, angielski, ...) – dotyczy komentarzy, opisów, dokumentacji, nazw
język programowania (pascal / delph, c, c++, c#,...) – dotyczy kodu źródłowego
kompilator
IDE
styl programowania (Paradygmat programowania): proceduralne, obiektowe, ...
metoda programowania: visual (Rapid application development RAD),
metodyki tworzenia oprogramowania: kaskadowy, ...
typ interfejsu użytkownika: CLI, TUI^[3], GUI, WUI, ...
licencja: GPL/Mozilla/shareware/commercial ...
cel (który procesor wykonuje kod): CPU, GPU
liczba wątków / procesów
system operacyjny (OS): DOS, windows (95, 98, ME, 2000, XP), Linux, MacOS, wieloplatformowy
platform sprzętowa (CPU i architektura): i386, i586,
typ komputera type: PC, ^[4]
data (utworzenie programu, poprawek)
źródło (adres internetowy repozytorium, strony domowej programu)
autor

Przykład:

{
spoken language: english
programming language: Pascal ( Borland object Pascal )
compiler: VER 140
IDE: Borland Delphi 7.0 personal edition
programming style : objective
programming method : visual (RAD)
target: CPU
number of microprocessors : 1 ; threads : 1 
library: standard =  VCL
program type : GUI application
licence: GNU GPL ; see  http://www.gnu.org/copyleft/gpl.html
OS: win32 (windows 98 SE
hardware: PC
platform:i386
author: 
Walbrzych/Poland/EU/europe/earth/Solar System/Milky Way/Universe (:-)))
2009.09.25
}

Czytnik dokumentacji

Zobacz również

Źródła

[1] Explaining Code using ASCII Art by John Regehr, Professor of Computer Science, University of Utah, USA

[2] rum ubuntu: Jak uruchomić Doxygena?

[3] Interfejs_tekstowy w wikipedii

[4] Typy komputerów w Wikipedii

[5] zeal strona domowa

[1]

[2]

[3]

[4]

[5]

Programowanie w systemie UNIX/dok

Cel