Course description

If you write instructions, procedures, user guides or help pages, or you're moving into a technical author role, this course shows you how to write documentation that people can follow first time.

You start with what technical writing is and who does it, then learn to find out who your readers are and what task they're trying to finish. You plan a documentation set with the right type of page for each need, write in plain English with consistent terms and a style guide, and write procedures with one action per step, clear results and well-placed cautions. You structure pages for scanning, use tables, screenshots and diagrams well and write alt text. You make documentation accessible and inclusive, review it with experts and watch real readers follow it. Then you write help pages, troubleshooting articles and error messages, look at API reference pages and code samples in outline, and learn to work with experts, manage a documentation project and build a portfolio.

There are 10 sections and 50 written lessons, each with a worked example, common slips, questions people often ask and a short exercise to try, and each section ends with a short quiz. You follow Seraphine, a support team leader who moves into a new technical author role at a small software company, as she plans, writes, reviews and publishes the documentation for a new feature. Every section has a practice pack with a worksheet, an answer key and a cheat sheet, plus an audience and task analysis template, a documentation plan template, a style guide template, a terminology spreadsheet, a procedure template, before and after rewrites, a review checklist and a glossary. The final project is a small documentation set for a made-up garden sensor, with worked answers to compare against.

What you'll learn

• What technical writing is: what it is and isn't, the roles of technical author, documentation writer and content designer, the life of a document and the tools of the job, described by type.
• Your audience and their task: who reads documentation and why, writing user needs, personas built from evidence and task analysis.
• Planning documentation: procedures, how-to guides, reference, concepts, troubleshooting, release notes and FAQs, topic-based writing, information architecture and a documentation plan.
• Plain English and style: plain words, short sentences, the active voice, consistent terms, a glossary, a style guide and editing your own draft.
• Writing procedures and instructions: the parts of a procedure, one action per step, results, conditions and choices, warnings and cautions, and numbered or bulleted lists.
• Structure, headings and visuals: headings for scanning, tables, screenshots, diagrams, annotated images, alt text and captions.
• Accessibility, inclusive language and review: accessible documentation, inclusive language, peer and expert review, usability walkthroughs, version control and change logs.
• Help pages, microcopy and developer documentation: help centres and knowledge bases, troubleshooting articles, microcopy and error messages, API reference pages and code samples in outline.
• Working with experts, projects and careers: working with subject matter experts, interviews, managing a documentation project, building a portfolio and finding work.
• Final project: a small documentation set for a made-up garden sensor: a getting-started guide, three procedures, a troubleshooting page, a glossary and a style sheet, with worked answers.

Who it's for

Adults moving into technical author or documentation roles, and staff who write procedures, user guides, help pages or work instructions as part of their job. You don't need a technical background or any experience of writing documentation.

What this course is, and isn't

This is an introduction to technical writing. It isn't a professional qualification. It names no software or companies: tools are described by type, so the skills work wherever you use them. Public guidance, such as the GOV.UK content and publishing guidance and the W3C accessibility guidelines, is described as it read when the course was written. Seraphine and every other person and product in the course are fictional.

What will I learn?

• Explain what technical writing is, the roles of technical author, documentation writer and content designer, and the life of a document
• Find out who your readers are, write user needs, build personas from evidence and break a task into steps
• Choose the right document type, write self-contained topics, organise a documentation set and write a documentation plan
• Write in plain English with short sentences, the active voice and consistent terms, backed by a style guide and a glossary
• Write procedures with one action per step, results, conditions, choices, warnings and cautions
• Structure pages for scanning, and use tables, screenshots, diagrams and alt text well
• Make documentation accessible and inclusive, and run peer reviews, expert reviews and usability walkthroughs
• Write help pages, troubleshooting articles, microcopy and error messages, and outline an API reference with code samples
• Work with subject matter experts, manage a documentation project and build a portfolio
• Produce a small documentation set for a made-up product: a getting-started guide, three procedures, a troubleshooting page, a glossary and a style sheet

Frequently asked questions