--- title: 'Technical writing syllabus' date: 2022-05-02 lastmod: 2022-05-02 last_updated: 2022-05-02 doc_version: '2022-05-02' description: '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. ' canonical: https://passo.uno/tech-writing-syllabus/ --- # 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 --- Canonical HTML version: https://passo.uno/tech-writing-syllabus/ ## Sitemap - [Full post index](https://passo.uno/sitemap.md) - [llms.txt](https://passo.uno/llms.txt)