Technisch schrijven

Documentatie geschreven vanuit het product, niet vanuit de spec

De meeste slechte documentatie is geschreven op basis van een eisenpakket of het geheugen van een developer. Ze beschrijft hoe de functie bedoeld was, niet het scherm dat de gebruiker daadwerkelijk ziet, met zijn hernoemde knop en zijn extra bevestigingsstap. De gebruiker volgt stap vier, vindt niets dat overeenkomt en opent een ticket.

We voeren elke procedure in het product uit voordat we hem opschrijven, op een testaccount, in de rol die de lezer zal hebben. Waar een stap anders werkt dan het team verwacht, loggen we dat, omdat documentatiewerk stelselmatig bugs aan het licht brengt die niemand had gemeld. Die lijst blijkt vaak net zo waardevol als de documentatie.

De taak scheiden van de uitleg

Een gebruiker die een factuur wil exporteren, wil niet eerst drie alinea's over het facturatiemodel. Een gebruiker die het facturatiemodel wil begrijpen, wil geen genummerde lijst met klikken. De twee in één artikel mengen maakt beide moeilijker te vinden en langzamer te lezen.

We splitsen content in taken (hoe doe je één ding), concepten (hoe iets werkt en waarom) en referentie (instellingen, velden, limieten, foutcodes). Elk type heeft een eigen template, zodat pagina's consistent blijven nadat we overdragen en uw team het veertigste artikel toevoegt.

De terminologielijst houdt het geheel door de tijd heen consistent. Als de interface 'werkruimte' zegt, noemt de documentatie hetzelfde ding nooit 'project' of 'account'. Het is een klein document dat de meeste verwarring die gebruikers melden voorkomt.

• Taakartikelen: één doel, genummerde stappen, het resultaat dat de gebruiker moet zien
• Conceptartikelen: het model achter een functie, met een diagram waar het helpt
• Referentiepagina's: elk veld, elke instelling en limiet, in een scanbare tabel
• Probleemoplossing: de foutmelding zoals geschreven, de oorzaak en de oplossing