Proces documentatie schrijven
Om een idee te geven over hoe een documentatieproject succesvol kan worden afgerond
volgt een opsomming van de verschillende fasen in een documentatieproject en
de betrokken personen.
Betrokken personen
De totstandkoming van documentatie is veelal geen éénmansproject. Hierbij zijn mensen
met verschillende rollen betrokken, die in de verschillende fasen van het traject
hun bijdrage leveren. Ten eerste is er de technisch schrijver, die is gespecialiseerd
in het kort en bondig formuleren van instructies en andere ondersteunende teksten.
Daarnaast is er de on line Help-specialist, die is gespecialiseerd in de verschillende
technieken en toepassingen voor het bouwen van een on line Help-systeem. In de praktijk
zijn de technisch schrijver en de on line Help-specialist vaak dezelfde persoon.
Verder zijn er één of meerdere deskundigen nodig die alles weten van het systeem
waarvoor de instructies worden geschreven. De deskundige is vaak een systeemontwerper,
programmeur of consultant. Deze deskundige moet de technisch schrijver van input
voorzien en beschikbaar zijn voor het beantwoorden van vragen van de technisch schrijver.
Daarnaast is er vaak een projectleider, die afspraken vastlegt, toeziet op de voortgang
van het project en het complete Help-systeem beoordeelt.
De toegevoegde waarde van een technisch schrijver ten opzichte van een systeemdeskundige
is dat de technisch schrijver naar het systeem kan kijken door de ogen van de eindgebruiker.
Hij zal dingen niet snel als bekend of vanzelfsprekend veronderstellen, zoals vaak
het geval is bij een specialist. De technisch schrijver kan snel zien waar een gebruiker
problemen zal ondervinden. Hierdoor zijn de teksten beter te begrijpen door de eindgebruikers.
Fasen
Het bouwen van een on line Help-systeem en het schrijven van de instructieteksten
kan worden uitbesteed aan een externe partij of worden uitgevoerd door eigen medewerkers.
In beide gevallen kunnen de volgende fasen in het project voorkomen:
- Analyse
- Afspraken vastleggen
- Input
- Schrijven
- Proeflezen
- Verwerken opmerkingen proeflezer
- Engineering
- Oplevering presentabel product
- Laatste beoordeling
- Eindoplevering
Analyse
Tijdens de analyse maken de schrijver en de opdrachtgever een overzicht van het
aantal Help-onderwerpen dat moet worden beschreven. Meestal wordt er per functie
van een programma een aparte tekst geschreven. Op basis van het aantal te beschrijven
onderwerpen kan een goede tijdsplanning worden gemaakt. Ook kunnen zij tijdens deze
fase bekijken welk Help-formaat het meest geschikt is en welke functionaliteit het
Help-systeem moet bevatten.
Afspraken vastleggen
Tijdens deze fase maken de schrijver en de opdrachtgever afspraken over het aantal
te schrijven Help-onderwerpen, de opzet van de Help-onderwerpen, het detailniveau
van de instructies, opmaak van de Help-onderwerpen, functionaliteit van het Help-systeem,
planning, enz. Deze afspraken kunnen worden vastgelegd in een projectplan.
Input
De opdrachtgever moet de technisch schrijver van informatie voorzien over de werking
van het systeem. De schrijver moet namelijk goed op de hoogte zijn van de manier
waarop de verschillende functies van het systeem werken. Meestal gebeurt de overdracht
door een deskundige van het systeem, zoals een programmeur, ontwerper of een consultant.
De informatieoverdracht kan op verschillende manieren plaatsvinden, zoals in de
vorm van persoonlijke interviews, reeds bestaande documentatie of trainingsmateriaal,
transactiefilms, enz. Ook stellen de schrijver en opdrachtgever een structuur op
voor de inhoudsopgave en/of navigatiemogelijkheden.
Schrijven
Aan de hand van de ontvangen input gaat de technisch schrijver de Help-teksten schrijven.
Meestal is er een Help-tekst per functie van het systeem. Deze teksten dienen er
consistent uit te zien, in overeenstemming met de afspraken die zijn gemaakt in
de afsprakenfase.
Proeflezen
Als de schrijver een concept klaar heeft van de Help-teksten, worden deze aan de
deskundige voorgelegd ter proeflezing. De deskundige krijgt nu de mogelijkheid om
te controleren of de instructies correct en volledig zijn. Hij stuurt zijn commentaar
terug naar de schrijver.
Verwerken opmerkingen proeflezer
Het commentaar, de opmerkingen, aanvullingen, enz. van de proeflezer worden door
de schrijver verwerkt, waarna de teksten klaar zijn.
Engineering
Nu kunnen er allerlei technische activiteiten worden uitgevoerd, zoals bijvoorbeeld
compileren, indexeren, Help-systeem optimaliseren voor de gebruikers, testen en
inbouwen van contextgevoeligheid.
Oplevering presentabel product
De schrijver levert het complete Help-systeem aan de opdrachtgever, zodat deze de
Help kan bekijken en eventueel verdere wensen en/of commentaar kenbaar kan maken.
Laatste beoordeling
De opdrachtgever bekijkt het presentabel product en kan hierop nog commentaar leveren.
Het is de bedoeling dat er alleen cosmetische veranderingen worden doorgevoerd.
De teksten zijn reeds nagekeken en behoren inhoudelijk dus in orde te zijn.
Eindoplevering
Het definitieve eindproduct wordt opgeleverd. Installatie van (ondersteunende) programma's
en bestanden kan hiervan deel uitmaken. Hierna is het project afgerond.
