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.