Zó heb ik mijn documentatie graag:
- Situering: grondige algemene uitleg; wat is (dit programma, deze computertaal, dit toestel, …), waar komt het vandaan, wie is ervoor verantwoordelijk, hoe verhoudt het zich tot de rest van de wereld, zijn concurrenten en alternatieven?
- Principes: wat, in grote lijnen, filosofisch bijna, zijn de grondslagen van het ding?
- Achter de schermen: hoe werkt het eigenlijk? Als ik op deze knop duw, deze link volg, deze hendel overhaal, wat gebeurt er dan precies?
- Naslag: geef een exhaustieve lijst van alle mogelijkheden, in detail, met kruisverwijzingen en telkens kadering in (1) en (2), en uitleg van (3).
- Voorbeelden: toepassingen, niet té gedetailleerd uitgelegd, maar wel goed kruisverwezen met (4).
- Links: bibliografie (on-line of off-line) waar ik meer informatie kan vinden, tussen te voegen overal waar het van toepassing is (dus van 1 tot en met 5).
Zo zou ik ook graag documentatie schrijven. Zo schreef ik vroeger ook documentatie en gaf ik vroeger opleidingen.
Helaas, helaas. Mensen zijn daar door de band hoegenaamd niet mee gediend.
Nee, mensen hebben liever:
- Vogelvlucht: wat is dit? en wat kan ik er mee doen?
- Voorbeelden: kijk, een aantal voorbeelden van wat mogelijk is!
- Recepten: kijk, een aantal recepten die je kan volgen om veel voorkomende problemen/vragen/taken op te lossen!
- Meer weten: beknopte en duidelijk geïllustreerde stap voor stap uitleg van recept(en)
- Nog meer weten: kort overzicht van plaatsen (on-line of ofline) waar meer informatie kan gevonden worden, met telkens duiding (dus geen alfabetische bibliografie, maar duidend: dit zijn de beste boeken, en dan kan je hier terecht, en dan…).
En weet je wat het fijne is? Dat men tegenwoordig met tinternet die twee ogenschijnlijk radikaal tegengestelde visies, die in een gewoon boek niet te verenigen zouden zijn, doodeenvoudig in elkaar kan vlechten.
Het is alweer heel erg lang geleden dat ik zelf nog ergens de één of andere vorm van gestructureerde opleiding gevolgd heb—boeken– en praktische zelfverworven kennis, weetuwel—maar ik vraag me af hoe lesgevers daar tegenwoordig mee omgaan.
Óf ze er mee omgaan.
Dan wel of ik met mijn hoofd in de wolken leef. 😀
De laatste opleiding die ik volgde was alvast van uw tweede type. Gelukkig! Want als een mens zich eerst door een hoop documentatie moet werken voordat hij kan beginnen clicken… pffft.
Maar inderdaad, aan het einde duurt die fragmentaire, rapid prototyping, XXX for dummies aanpak een heel stuk langer dan de grondige.
Dat geldt trouwens ook voor het ontwerpen/ontwikkelen van softwaretoepassingen.
Wel, ‘t is geen kwestie van sneller/trager denk ik, maar gewoon van types mensen. En van het onderwerp hangt ook veel af natuurlijk.
En, natuurlijk, in alle types zijn er goeie en slechte voorbeelden aan te halen–lees deze voor een hele reeks uitstekende voorbeelden.
Mijn favoriet is overigens Why’s (Poignant) Guide to Ruby, dat gewoon sui generis is. 🙂
Top tip. Ik hou van scenario één, maar geloof eveneens dat de tweede het bredere publiek treft.
Steven! Uit het verre Ginderachterland!