Technical writing syllabus

A few months ago, I drafted a technical writing syllabus. It features all the topics that a senior technical writer should master at some point when working on software documentation.

Note that this is not a course (yet). I plan to set aside some time to develop each module into video training materials, but for now it’s just a a shopping list. If you want to follow the syllabus, finding materials is up to you.

Introduction

There’s never been a better time for technical writing. With the rise of software companies and startups, technical documentation, from manuals to UX writing to API documentation, is becoming a priority for companies wishing to improve the way their products communicate and reach an even wider user base. If a product isn’t documented, it doesn’t exist.

This draft syllabus is aimed at graduates of any degree wishing to start a career in software documentation. The only requirements are a passion for writing in English, a journalistic appetite for understanding how things work and for simplifying the complex, and a fearless, practical attitude towards technology and software programming.

Module I - Write

Introduction to technical communication

What is this all about? Why should you care?

• Simplifying the complex: the importance of TC
• History and trends in technical communication
• Technical communication as a profession
• Technical communication in software companies

English for technical writers

Technical English is not Joyce’s English. It’s more like Hemingway’s.

• Essentials of technical English
• Coaching writers: editing and proofreading
• Tools: Style guides and prose linters
• Facilitating technical translation: l10n and i18n

Writing for the web

Same words, different medium.

• Principles of information architecture
• SEO and beyond: Writing for search engines and humans
• UX writing: Writing in web user interfaces
• Content strategy: Going for the bigger picture

Documentation tools

Navigate the extensive tooling ecosystem for documentation.

• Classic docs: from Word to Wikis
• Structured content: DITA, DocBook, Lightweight DITA
• Paligo, MadCap Flare, and other CCMS
• Markup languages: MD, RsT, Asciidoc, MarkDoc

Module II - Visualize

Technical illustration

A picture can be worth a thousand words – when done well.

• Principles of visual communication
• Types of visuals for technical communication
• Diagrams and flowcharts: From UML to Bikablo
• Taking screenshots: SnagIt, Greenshot, and others

Video and animation

A great video can be worth a million words. Learn the basics of screencasting.

• Scripting for technical documentation
• Screencast: from recording to releasing
• Screen recording tools: Camtasia, GIFs, Premiere
• Voiceover and dubbing

UX and Usability

Technical writing is designing interfaces using words.

• Usability for writers: from the F pattern to typography
• Good and bad UX and DX
• Tools and methods of UX design
• User research and user interviews

Module III - Code

Software development methodologies

Embed in development teams by understanding how they work together.

• Software development methodologies: from Waterfall to Agile
• Agile for technical writers: Scrum, Kanban, and beyond
• Working in agile teams: tools, ceremonies, embedding
• Building a docs culture at companies

Writing for software development

Internal documentation requires a slightly different mindset.

• Documentation in the code
• Code-generated documentation
• Internal technical documentation
• Writing for the command line

Programming basics

Know enough programming to be dangerous. Great technical writers are bad coders.

• The UNIX command line
• HTML5 and CSS
• Python for technical writers
• Cloud computing essentials

Module IV - Document

Docs-as-code bootcamp

Learn the principles of modern technical writing for software.

• Version control for writers: Git, GitHub, etc.
• Plain text documentation: Markup languages (MD, RsT, Asciidoc)
• Static-site-generators and headless CMS
• Pandoc and format converters

Documenting Web APIs

API documentation is both a design and documentation activity.

• Introduction to Web API: REST, GraphQL, HTTP
• API first design and technical writing
• OpenAPI and GraphQL specifications
• Talk to APIs: Curl, Postman, and others

Your documentation project

Time to put everything into practice.

• Internship in one of the sponsoring companies
• Improve the docs of an open source project
• Build your own docs-as-code toolchain
• Other projects (documentation software, translation, etc.)

A word on metrics and KPIs

How to know if the docs are successful.

• KPIs, OKRs, and other success criteria
• Using web analytics to gauge docs metrics
• Feedback forms, feedback widgets, and NPS
• The importance of user research