Hoe schrijf ik technische documentatie

Als het gaat om het opstellen van technische documentatie, zijn er een redactionele richtlijnen waarmee rekening gehouden moet worden. Technische documentatie is het resultaat van teamwerk. Meerdere auteurs werken aan verschillende documenten en toch moet het één helder, goed opgebouwd dossier opleveren. Auteurs brengen hun eigen redactionele stijl mee. Dat is niet per se verkeerd en kan zeker helpen om een goed eindresultaat af te leveren, mits het team deze inbreng adopteert en het niet leidt tot inconsistente documentatie of methodologische verscheidenheid – een absolute no-go in de documentatiewereld. Het risico hierop wordt vergroot als nieuwe leden aan het team worden toegevoegd, het team verspreid is over meerdere locaties, of wordt samengewerkt met externe partijen. De gevolgen worden met name merkbaar als een belangrijke materiedeskundige verdwijnt en zijn of haar waardevolle kennis niet meer beschikbaar is omdat het niet duidelijk en terugvindbaar op papier is gesteld.

De remedie is een aantal centrale uitgangspunten, zoals hieronder geformuleerd.

Herkenbare opbouw

Consistentie is een essentieel kwaliteitskenmerk van goede technische documentatie. Het helpt gebruikers om de informatie gemakkelijker op te nemen en verhoogt de begrijpelijkheid. Consistentie vindt je terug in de hoofdstuk opbouw, de document identificatie en revisiebeheer, de kop- en voetteksten, maar ook in het gebruikt van terminologie en formulering van bepaalde concepten, zoals het beoogd gebruik, klinisch voordeel, naamgeving, et cetera. Gebruikte termen moeten de lading dekken en niet tot begripsverwarring leiden. Een centrale woordenlijst kan hierbij helpen, evenals een Bill of Materials die materiaal identificatie nummers en materiaalnamen specificeert. Bedrijfsmiddelen worden van een asset nummer voorzien.

Structurering en vormgeving van de informatie, en overkoepelende procedures voor het beheer van registraties, leiden tot een uniforme aanpak, het professionaliseren van het technisch redactioneel werk en het bereiken van een constant hoog niveau van documentkwaliteit. Duidelijke en begrijpelijk geformuleerde stijlregels maken het werk van technische redacteuren veel gemakkelijker.

Onduidelijke processen, ongedefinieerde verantwoordelijkheden of onduidelijke documentsjablonen kunnen een enorme impact hebben op de samenwerking binnen het team en op de motivatie van medewerkers. Ze leiden tot begripsverwarring of hiaten en tegenstrijdigheden binnen het dossier. Technische documentatie moet daarom altijd worden bekeken en geredigeerd door de gebruikers, voordat het wordt vrijgegeven. De gebruiker moet deze reviewtaak serieus nemen om gebruikers in de verre toekomst een plezier te doen.

Informatie met toegevoegde waarde

Technische documentatie is een investering. Het kost veel tijd en dus geld om de technische documentatie goed op te stellen. Maar het kost veel meet tijd en geld als de documentatie onzorgvuldig is opgesteld. Dus kun je er maar beter voor zorgen dat de technische documentatie ook daadwerkelijk waarde toevoegt aan het project en de organisatie. Welke waarde kan technische documentatie onder andere toevoegen:

• Het levert de informatie aan de operationele omgeving op basis waarvan zij het product op reproduceerbare wijze kunnen fabriceren.
• Het geeft inzicht in alle aspecten van het product op basis waarvan risico’s tot een minimaal en acceptabel niveau kunnen worden beperkt en de prestatie kan worden gemaximaliseerd.
• Het levert de nodige informatie bij het beoordelen van tekortkomingen en klachten. Mogelijke oorzaken kunnen hierdoor sneller worden gevonden.

Omdat een technisch document een specifiek doel moet dienen en nuttig moet, moet het praktisch en to the point zijn. Daarbij hoort een taalgebruik dat past bij de doelstelling. Gebruik kwantitatieve woorden in plaats van vage kwalitatieve termen. Zo ontving ik onlangs een analysecertificaat waarbij een bepaalde eigenschap werd beoordeeld als zijnde “in overeenstemming” zonder dat duidelijk was waarmee het dan in overeenstemming was en wat specifiek de meetbare criteria waren aan de hand waarvan het waardeoordeel “in overeenstemming” of “niet in overeenstemming” werd bepaald.

Logisch en samenhangend

De informatie die in een document geleverd wordt moet een duidelijk verhaal bieden. Wat is het doel van het document, waar gaat het over (welk product en welk moment in de ontwikkeling), wat zijn de feiten, uit welke bronnen zijn deze afkomstig en hoe onderbouwen deze feiten de conclusie.

Bij het schrijven van technische documenten is het essentieel dat de achtergronden en voorkeuren van de gebruikers van de documenten wordt begrepen. Wanneer wordt het document door wie gebruikt en op welke vragen biedt het document een antwoord? Is het document logisch opgebouwd, zodat het antwoord ook gemakkelijk tussen alle overige informatie gevonden kan worden? Wordt er gebruik gemaakt van structuren die hierbij helpen: hoofdstuk titels, bullit points, tabellen, en grafische presentatie van de informatie? Succesvolle visuals integreren inhoud en vormgeving om duidelijkheid en efficiëntie te bereiken. De beste visuals geven de lezer zo snel mogelijk de meeste informatie in zo klein mogelijk ruimte.

De technische documentatie wordt vastgelegd meerdere documenten, die onderlinge relaties met elkaar hebben. Deze relaties moeten voor de lezer te volgen zijn. De structuur binnen het dossier moet logisch zijn. Een standaard structuur voor de technische documentatie voor alle producten van de organisatie vergroot de herkenbaarheid en terugvindbaarheid.

Toekomstbestendig

Ontwikkelingen staan niet stil. Misschien wil je de productgroep uitbreiden met nieuwe modellen. Misschien is het eerste product een voorloper voor een beter product. De technische documentatie moet zo zijn opgesteld dat de resultaten van verdere ontwikkeling er eenvoudig aan kunnen worden toegevoegd en kunnen worden ingepast is de opbouw van het dossier. Integreren van nieuwe ontwerpen moet niet leiden tot duplicatie van informatie over de algemene kenmerken van de productgroep. Deze documenten moeten eenvoudig toepasbaar worden gemaakt voor nieuwe ontwerpen. Nieuwe documenten moeten in principe alleen worden toegevoegd om de specifieke eigenschappen van nieuwe ontwerpen te adresseren.

Consistentie in de opbouw van elk document maakt de documentatie toekomstbestendiger. Ook de relationele opbouw in het dossier bevordert de toekomstbestendigheid.

Up-to-date

Maar ook de industriële ontwikkeling staat niet stil, evenals de ontwikkeling van nieuwe normen en regelgeving. Technische documentatie moet kunnen worden aangepast om aan nieuwe vereisten te kunnen voldoen. De technische documentatie moet traceerbaar zijn naar de toegepaste norm en de betreffende revisie om aan te tonen dat het ontwerp in overeenstemming is gebracht met de state-of-the-art eisen.

Kortom

Redactionele richtlijnen zijn nuttig voor iedereen die betrokken is bij het maken en gebruiken van technische documentatie. Dit geldt net zo goed voor een groot team van 10 medewerkers en extra ondersteuning van een dienstverlener, als voor een klein team van twee personen. Immers, iedereen wil met minimale inspanning overzicht houden.