Technical documentation

Engelsk A (HTX) · HTX · A-niveau · Technical English

🇬🇧 Technical documentation

Technical documentation = skriftlig kommunikation om tekniske produkter eller processer.

Hovedtyper:

1.

User manuals: hvordan bruger end-users produktet. Step-by-step instruktioner med billeder. Apple's manuals = guldstandard for klarhed.

2.

API documentation: developers' reference. Struktur: endpoints, parameters, return values, examples. Stripe og Twilio's API-dokumentation = berømt for kvalitet.

3.

System documentation: arkitektur-overblik for vedligeholdere. Diagrammer (UML, C4 model).

4.

Process documentation: SOP (Standard Operating Procedures), runbooks.

5.

Specification documents: kravspec, design-dok.

6.

Release notes: hvad er nyt i version X.Y.Z.

Documentation as code: skriv i Markdown/AsciiDoc, versionér i Git, generér med tools (MkDocs, Sphinx, Docusaurus).

Documentation-driven development: skriv dokumentation FØR koden. Tvinger klar tænkning.

DocOps/Docs as Code-bevægelsen: behandl docs som software — review, test, CI/CD.

Diagrammer: PlantUML, Mermaid (tekstbaseret diagram-syntax). Architecture diagrams (C4 model af Simon Brown), sequence diagrams, ER-diagrams.

Style guides: Microsoft Style Guide, Google Developer Documentation Style Guide. Konsekvent terminologi, voice, format.

Localization: oversæt til flere sprog. Kompliceret pga. tekniske termer der varierer.

Accessibility: alt-tekst på billeder, klare overskrifter, læsbar font. WCAG 2.1.

Eksempler

Linux man pages (klassisk), Stripe API do

Læringsmål

• Redegøre for principper for klar teknisk dokumentation på engelsk
• Skrive en brugervejledning eller teknisk beskrivelse
• Vurdere dokumentations målgruppetilpasning

Sådan kan du arbejde med emnet

• Write a short set of instructions in English for using a piece of software or equipment you know well
• Discuss what makes technical documentation easy or hard to follow, using an example you have read
• Translate a short Danish technical instruction into clear English and compare the two versions

Læs originale tekster, lyt til autentiske kilder og skriv egne tekster på sproget.