noxqs.org's

FROG
FRee-open-source project-lOG

- documentatie die zeker werkt is html: te schrijven met een eenvoudige txt-verwerker tot Webeditor als Quanta. Raadplegen kan met eender welke browser, er kan uit gekniopt en geplakt worden, een copy op CD kan zelfs als documentatie gebruikt worden. Maar moet je zelf alles organiseren: inhoud, verwijzingen, … en als je wil werken vanop verschillende locaties of met meer deelnemers wordt het omslachtig.

- om gemakkelijk tekst online te krijgen, te raadplegen via browser, en waarbij de inhoud ook gevuld kan worden via een browser lijkt het gebruik van een wcms voor de hand te liggen, bv phpbb, waarbij je rubrieken zo indeelt dat ze overeenkomen met wat je nodig hebt. Hier is het wel moeilijk om er bv een pdf-handleiding uit te halen nadien en ook de applicatie aanpassen aan je noden is extra werk.

- wiki: web-interface lezen, en even web-interfaced online schrijven; plaatselijk (online) te installeren, bijdragen en uitbreidingen doorlopend mogelijk ook door gebruikers van de documentatie.

Dit zijn command-line systemen, voor een LAMP project minder geschikt:
- Texinfo: gebruikt door de free software foundation (GNU) om documentatie te schrijven bij hun software. Bedoeld voor het gebruik met “info”, de command prompt lezer (bv “info tex” geeft op command prompt uitleg over tex). Heeft goede uitvoer voor gedrukt werk. Niet duidelijk of er goede html uitvoer is.
- man: standaard systeem op linux om “manuals” te maken die geraadpleegd worden met het command line programma “man”, bv “man help” om uitleg over “help” te krijgen. (vgl info)

- Docbook ziet er interessant uit. Is het makkelijk aan te leren of te beginnen gebruiken?
- …

Hoe op een goede manier je LAMP-project documenteren, en hoe een nuttige handleiding maken voor de gebruikers van de software? Voor documentatie van de software kan je er van uit gaan dat de ontwikkelaar dat automatisch doet, maar misschien is die wel van het principe “het programma is de documentatie”. In zekere zin is dat ook zo bij open source software, zoals het ook bij script-talen voor de hand ligt. Een MySQL database is ook geen geheime zwarte doos en laat toe de struktuur te onderzoeken of exporteren. Maar toch.

Voor de gebruikersdocumentatie is het anders, de ontwikkelaar kan niet aan alle gebruikers uitleg gaan geven. Een handleiding of gebruikersdocumentatie is dus nodig. Om achteraf geen tijd te verliezen zou heel wat uitgezocht moeten worden voor je de documentatie begint te maken:

Wat is het makkelijkste formaat? Moet het gedrukt worden? PDF? Of moet het online geraadpleegt worden (logisch bij een web-interface)? Schrijf je die dan als html? En bestaan daar vrije-software tools voor om dat te doen? Als er meer dan 1 taalversie van moet gemaakt worden zal dat ook invloed hebben op het maken van de documentatie; eerst in 1 taal? Welke? Moeten de gebruikers de handleiding kunnen aanvullen (zoals in wiki-systeem)? Moet de handleiding geïntegreerd zijn of afzonderlijk kunnen verspreid worden?

Ik heb helaas alleen nog maar de vragen…