Klik hier om te helpen David McMurrey betaal voor webhosting:
Doneer elk klein bedrag dat je kunt!
Online technische schrijven blijft gratis.

Technische documenten (zoals handleidingen, whitepapers en gidsen) hebben verschillende ontwerpen, afhankelijk van de industrie, het beroep of de organisatie. Dit hoofdstuk toont je één traditioneel ontwerp. Als je een cursus technisch schrijven volgt, zorg er dan voor dat het ontwerp dat in dit hoofdstuk wordt gepresenteerd, acceptabel is. Hetzelfde geldt als je een technisch document schrijft in een wetenschappelijke, zakelijke of overheidscontext.

NotebookLM-generated infographic of this chapter NotebookLM-gegenereerde infographic van dit hoofdstuk

Opmerking: Jarenlang werd deze online handleiding voor technische schrijvers rapporten in het algemeen aangeduid als praktisch alles wat technische informatie bevat. Maar omdat "rapport" verwijst naar een specifiek genre van technische documenten, moest de wijziging worden aangebracht naar het algemene "techdoc," een afkorting voor technisch document.

Techdocs (algemene naam voor technische documenten) hebben specificaties, net als elk ander soort project. Specificaties voor techdocs omvatten lay-out, organisatie en inhoud, opmaak van koppen en lijsten, het ontwerp van de graphics, enzovoort. Het voordeel van een vereiste structuur en opmaak voor techdocs is dat jij of iemand anders kan verwachten dat ze op een bekende manier zijn ontworpen—je weet waar je op moet letten en waar je het moet zoeken. Techdocs worden meestal snel gelezen—mensen hebben haast om de informatie te krijgen die ze nodig hebben, de belangrijkste feiten, de conclusies en andere essentiële zaken. Een standaard techdoc-formaat is als een bekende buurt.

Wanneer je het ontwerp van een techdoc analyseert, merk dan op hoe repetitief sommige secties zijn. Deze duplicatie heeft te maken met hoe mensen techdocs lezen. Ze lezen techdocs niet van begin tot eind: ze beginnen misschien met de samenvatting voor het management, springen rond en lezen waarschijnlijk niet elke pagina. Jouw uitdaging is om techdocs te ontwerpen zodat deze lezers jouw belangrijke feiten en conclusies tegenkomen, ongeacht hoeveel van de techdoc ze lezen of in welke volgorde ze het lezen.

Zorg ervoor dat je de voorbeeld techdocs.

De standaardcomponenten van het typische technische rapport worden in dit hoofdstuk besproken. De volgende secties begeleiden je door elk van deze componenten en wijzen op de belangrijke kenmerken. Terwijl je deze richtlijnen leest en gebruikt, onthoud dat dit richtlijnen zijn, geen geboden. Verschillende bedrijven, professies en organisaties hebben hun eigen uiteenlopende richtlijnen voor technische documenten—je zult je praktijk moeten aanpassen aan die, evenals aan de hier gepresenteerde.

Verzendbericht

Het verzendbericht is ofwel een begeleidende brief (of memo) of een e-mail. De fysieke brief (of memo) is ofwel aan de buitenkant van de techdoc bevestigd met een paperclip of binnenin de techdoc gebonden. De e-mail bevat een link naar de techdoc of heeft de techdoc als bijlage. Het is een communicatie van jou—de techdoc schrijver—naar de ontvanger, de persoon die de techdoc heeft aangevraagd en die je misschien zelfs betaalt voor je deskundig advies. Het zegt in wezen: "Oké, hier is de techdoc die we hebben afgesproken dat ik zou afronden voor een bepaalde datum. Kort samengevat, bevat het dit en dat, maar dekt het dit of dat niet. Laat me weten of het aan je behoeften voldoet." Het verzendbericht legt de context—de gebeurtenissen uit die tot de techdoc hebben geleid. Het bevat informatie over de techdoc die niet in de techdoc thuishoort.

Business letter and email versions of transmital message
Voorbeelden van een verzendbrief en verzendbericht.

In het voorbeeld van de verzendbrief, let op het standaard zakelijke briefformaat. Als je een interne techdoc schrijft, gebruik dan in plaats daarvan het memorandumformaat; in beide gevallen zijn de inhoud en de organisatie hetzelfde:

Eerste alinea. Citeert de naam van de techdoc, deze cursief zetten. Het vermeldt ook de datum van de overeenkomst om de techdoc te schrijven.

Middeldeel. Focust op het doel van de techdoc en geeft een kort overzicht van de inhoud van de techdoc.

Laatste alinea. Moedigt de lezer aan om contact op te nemen als er vragen, opmerkingen of zorgen zijn. Het sluit af met een gebaar van goede wil, met de hoop dat de lezer de techdoc bevredigend vindt.

Zoals bij elk ander element in een technische documentatie, moet je mogelijk de inhoud van dit bericht (of memo) aanpassen voor specifieke situaties. Je wilt bijvoorbeeld misschien een extra alinea toevoegen, met vragen die je de lezers wilt laten overdenken terwijl ze de technische documentatie doornemen.

Omslagen, Titelpagina en Label

Als je techdoc meer dan tien pagina's is, bind het dan op een of andere manier en maak een label voor de omslag.

Dekens

Omslagen geven technologische documenten een solide, professionele uitstraling en bescherming. U kunt kiezen uit vele soorten omslagen. Houd deze tips in gedachten:

Over het algemeen zijn losse bladen notitieboeken of ringbanden minder voorkeur waard. Deze zijn te omvangrijk voor korte techdocs en de gaatjes in de pagina's hebben de neiging te scheuren. Natuurlijk maakt de ringband het gemakkelijk om pagina's te verwisselen; als dat is hoe je techdoc gebruikt zal worden, dan is het een goede keuze. Aan de "hoge kant" zijn de overmatig luxe omslagen met hun kunstlederen uitstraling en goudkleurige afwerking. Vermijd ze—houd het eenvoudig, simpel en functioneel.

Titelpagina

In zijn eenvoudigste vorm is een techdoc-titel een kopie van wat op de voorkant staat—mogelijk met een paar toegevoegde details.

Bekijk de titelpagina Abstract en Executive Summary.

Labels

Zorg ervoor dat je een label bedenkt voor de omslag van je techdoc. Het is een stap die sommige techdoc-schrijvers vergeten. Zonder een label is een techdoc anoniem; het wordt genegeerd.

De beste manier om een label te maken is om je tekstverwerkingssoftware te gebruiken om er een te ontwerpen op een standaard pagina met een grafische box rond de labelinformatie. Print het uit, ga dan naar een copyshop en laat het rechtstreeks op de techdoc hoes kopiëren.

Er staat niet veel op het label: de titel van het techdoc, uw naam, de naam van uw organisatie, een trackingnummer voor het techdoc en een datum. Er zijn geen standaardvereisten voor het label, hoewel uw bedrijf of organisatie zijn eigen vereisten zou moeten hebben. (Een voorbeeld van een techdoc-label is hieronder weergegeven.)


Verzendbrief en technische documentatie omslag (met omslaglabel).

Samenvatting en Uitvoeringssamenvatting

De meeste technische documentatie bevat minstens één samenvatting—soms twee, waarbij de samenvattingen verschillende rollen spelen. Samenvattingen geven een overzicht van de inhoud van een technische documentatie, maar de verschillende types doen dit op verschillende manieren:

Als de executive summary, inleiding en verzendbericht je repetitief lijken, onthoud dan dat lezers niet noodzakelijkerwijs beginnen bij het begin van een techdoc en pagina voor pagina naar het einde lezen. Ze springen rond: ze kunnen de inhoudsopgave scannen; ze bladeren meestal snel door de executive summary voor belangrijke feiten en conclusies. Ze kunnen slechts een sectie of twee uit de hoofdtekst van de techdoc aandachtig lezen, en vervolgens de rest overslaan. Om deze redenen zijn techdocs ontworpen met enige duplicatie, zodat lezers zeker de belangrijke informatie zien, ongeacht waar ze de techdoc binnenkomen.


Inhoudsopgave (wat eerst komt) dan de samenvatting.

Inhoudsopgave

Welke inhoudsopgave (TOC) formaat je ook gebruikt, dit zijn de algemene normen: