Tekninen kirjoittaminen

Dokumentaatio kirjoitettu tuotteen näkökulmasta, ei teknisen spesifikaation mukaan

Huonoimmat dokumentaatiot on usein kirjoitettu vaatimusmäärittelyn tai kehittäjän muistin varassa. Ne kuvaavat ominaisuuden tarkoitettua toimintaa, eivät sitä näyttöä, jonka käyttäjä todellisuudessa näkee – mukaan lukien nimetty painike ja ylimääräinen vahvistusvaihe. Kun käyttäjä seuraa neljättä vaihetta, ei löydä vastaavaa ja avaa tukipyyntöä.

Suoritamme jokaisen toimenpiteen tuotteessa ennen sen kuvaamista testitilillä, käyttäen lukijan roolia. Jos vaihe poikkeaa tiimin odotuksista, merkitsemme sen ylös, koska dokumentaatiotyö paljastaa säännöllisesti bugeja, joita kukaan ei ollut raportoinut. Tämä lista osoittautuu usein yhtä arvokkaaksi kuin itse dokumentaatio.

Erota tehtävä selityksestä

Käyttäjä, joka haluaa viedä laskun, ei tarvitse kolmen kappaleen esittelyä laskutusmallista etukäteen. Käyttäjä, joka ymmärtää laskutusmallia, ei tarvitse numeroitua klikkauslistaa. Kahden yhdistäminen samaan artikkeliin tekee molemmista vaikeampia löytää ja hitaampia lukea.

Jaamme sisällön tehtäviin (miten tehdä yksi asia), käsitteisiin (miten jokin toimii ja miksi) ja viitetietoon (asetukset, kentät, rajat, virhekoodit). Jokaisella tyypillä on oma malline, joten sivut pysyvät johdonmukaisina myös sen jälkeen, kun olemme luovuttaneet työn ja tiimisi lisää fortieth artiklan.

Terminologialuettelo pitää joukon koherenttina ajan myötä. Jos käyttöliittymässä sanotaan 'työtila', dokumentaatiossa ei koskaan käytetä sanaa 'projekti' tai 'tili' samalle asialle. Se on pieni asiakirja, joka estää suurimman osan käyttäjien raportoimasta hämmennyksestä.

• Tehtäväartikkelit: yksi tavoite, numeroitut vaiheet, lopputulos, jonka käyttäjän tulee nähdä
• Käsiteartikkelit: ominaisuuden takana oleva malli, kaavio tarvittaessa
• Viitesivut: kaikki kentät, asetukset ja rajat selattavassa taulukossa
• Vianmääritys: virheilmoitus sellaisenaan, sen syy ja korjaus