Technical writing syllabus
May. 2, 2022
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.
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
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
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
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
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