Awesome Technical Writing Learning 
Technical writing is an essential skill of conveying complex technical information in an easy-to-understand way.
[!TIP] All resources in this curated list are free, unless otherwise noted.
Want to suggest a resource? Check out the Contribution Guidelines! 👐
Contents
- Technical writing
- Technical illustrations
- Authoring formats
- Content accessibility
- Text processing
- Version control
- Knowledge sharing
- Professional communications
Technical writing
Writing is a skill, not a talent, and this difference is important because a skill can be improved by practice.
Courses for beginners
If you are completely new to technical writing, the following 🔔 courses are the best starting points for you:
- Google Technical Writing Courses for Engineers - Practical technical writing course for beginners, with examples and metaphors familiar to programmers.
- Google Technical Writing Courses for Engineers (accessible in China)
- GitLab Technical Writing Fundamentals Course - four introductory videos about the topic types, grammars, and style requirements for GitLab documentation.
- Coursera: Introduction to Technical Writing - Systematic introduction to technical writing, including the features, workflow, software and tools, history and futures, etc.
Textbooks and tutorials
Now, you know a bit about technical writing 👏! Not enough for you? Let’s go further 🤠!
The following 📚 textbooks and tutorials authored by experienced professionals are great resources for you to systematically learn a new skill. Here you are, enjoy 😄!
- Software Technical Writing: A Guidebook - A technical writer at a computer vision startup writes about her daily work in every detail.
- Documentation APIs: A Guide for Technical Writers and Engineers - Tom Johnson, a senior technical writer at Google and the founder of the I’d Rather Be Writing blog, teaches you how to write API documentation step by step.
- Software Documentation Guide - Living guide around best practices for creating software documentation, developed and maintained by the Write the Docs community.
- Developing Quality Technical Information: A Handbook for Writers and Editors - One of the must-read books for technical writers. It demonstrates technical writing guidelines with original and revision examples, published by IBM Press.
- Open Technical Communication - Open textbook in its 4th rendition, authored by five professionals at Kennesaw State University.
Editorial style guides for technical writing
Learning by doing, rather than learning by reading.
But wait a minute, you still need to adopt an 📙 editorial style guide for technical writing at first. If you forget what editorial style guides are or why you need one, go back to Google Technical Writing Courses for Engineers for a refresher.
- ASD-STE100 Simplified Technical English - An international specification widely used in the aerospace and defense industry and other manufacturing industries, containing a set of writing rules and a controlled dictionary.
- The IBM Style Guide - First published by IBM Press in 2011. It emphasizes a helpful, direct, and authoritative tone and topic-based writing (DITA).
- Red Hat Technical Writing Style Guide - For all kinds of technical documentation, including training and examination content. It emphasizes a formal writing style, with the IBM Style Guide as the preferred reference.
- Red Hat Supplementary Style Guide for Product Documentation - Supplementary to the IBM Style Guide. It provides format examples in AsciiDoc.
- Microsoft Writing Style Guide - For computer technology and software documentation. It emphasizes a warm and relaxed conversational voice.
- Google Developer Documentation Style Guide - For software documentation. It emphasizes a casual and natural conversational tone with specific format recommendations for HTML and Markdown.
- GitLab Documentation Style Guide - For open source software documentation written in Markdown. It emphasizes topic-based writing and format guidelines for Markdown.
- SUSE Documentation Style Guide - For software documentation. It emphasizes a professional tone and comprehensive markup reference for DocBook.
- Apple Style Guide - For Apple materials, nothing special.
General purpose editorial style guides
In the real world, anything is possible. Take a suitable 📙 general purpose editorial style guide at hand, in case you step into an unknown situation someday.
- University of Oxford Style Guide Quick Reference - One-page quick reference guide with the most commonly requested information.
- University of Oxford Style Guide - Thirty-page style guide for writing and formatting documents consistently.
- Chicago Manual of Style - Over 1000 pages. It has been published continuously since 1906 and now is in its 17th edition (subscription required).
- AMA Manual of Style - For medical and scientific publishing. It has been published continuously since 1962 and now is in its 11th edition (subscription required).
Dictionaries
And you know, select a suitable 📘 dictionary too!
Now, you can use your writing skills to improve your technical documentation!
Writing assistant software
- Grammarly - Online grammar checker that automatically evaluates writing quality.
- QuillBot - Online grammar checker and rewriting tool.
- LanguageTool - AI-based spelling, style and grammar checker.
- ChatGPT - AI chatbot developed by OpenAI.
- Tongyi Qianwen - ChatGPT-like chatbot developed by Alibaba, one of China’s largest technology companies.
Readability checkers
- Free Readability Checker - For web pages (URL) and texts.
- Readability Formulas - For documents (.txt, .pdf, or .docx) and texts.
- Wordcalc - For texts only.
Technical illustrations
A picture is worth a thousand words.
High-tech industries usually rely heavily on technical illustrations in their technical documentation, such as manufacturing, automotive, aerospace, and defense. But unfortunately, there are few resources available 🤓.
- Technical Illustration in the 21st Century: A Primer for Today’s Professionals - White paper produced by Bettina Giemsa at PTC.
- The State of Technical Illustration and Documentation - Survey report on technical illustration and documentation market, conducted by Corel in 2022.
Technical illustrators used to create technical illustrations using Adobe Illustrator or CAD. However, 💻 software designed specially for technical illustrations is becoming more and more popular in these days.
- Arbortext IsoDraw Data Sheet and Arbortext IsoDraw Online Help - Commercial software for technical illustrations, developed by PTC.
- SOLIDWORKS Composer and SOLIDWORKS Composer Help - Commercial software for technical illustrations, developed by SolidWorks.
- XVL Studio 3D CAD Corel Edition - Commercial software for technical illustrations, developed by CorelDRAW.
- XVL Technical Illustration Suite - A suite of commercial software for technical illustrations, developed by Lattice Technology.
Authoring formats
Going with the trend of Docs as Code, more and more organizations and their technical writers have ditched word processors and switched to markup languages.
Markdown
Markdown is a lightweight markup language created by John Gruber in 2004. It has become a commonly used markup language to write technical documentations, especially those software documentations that host in GitHub or GitHub-like platforms.
If you are completely new to Markdown, the following 📔 guide is the best starting point for you:
- Markdown Guide - Concise, bare-bones guide for Markdown beginners.
- John Gruber’s Markdown Documentation
Now, you know a bit about Markdown 👏. It is easy-to-read, easy-to-write, and easy-to-learn, isn’t it 😎?
Can’t wait to try it out? Just adopt a ✒️ Markdown editor, then you are ready 💪!
- Dillinger - In-browser Markdown editor. It can create new files, export files to Markdown, HTML, or PDF, synchronize with GitHub, Google Drive, or Dropbox repositories, etc.
- StackEdit - In-browser Markdown editor with rich functions. It can create new files or folders, export the files to Markdown or HTML, synchronize with GitHub, Google Drive, or Dropbox accounts, etc.
- Visual Studio Code (VS Code) - Code editor developed by Microsoft, with built-in Markdown preview and many Markdown extensions.
- Markdown All in One - An extension to enrich Markdown features in VS Code, such as automatic creation of table of contents, auto completions, printing Markdown files to HTML.
- Markdown Table Maker - An extension to generate Markdown tables in an easy and intuitive way.
- Markdown PDF - An extension to convert Markdown files to PDF, PNG, JPEG, or HTML.
- Markdown Preview Enhanced - An extension to enrich Markdown features in Atom and VS Code, featuring the integration of Pandoc.
If you go deeper, you will find the controversy over Markdown.
As Markdown got popular, more and more Markdown parsers appeared. However, Markdown has no well-accepted standard until now. The Markdown syntax in each parser is to some extent different from others.
As a result, whenever you select a new Markdown tool, you must read through its 📙 user manual or documentation to know exactly what Markdown syntax it supports.
- GitHub Docs: Writing on GitHub - Basic Markdown syntax supported on GitHub.
- GitHub Flavored Markdown Specification
- Markdown DITA Syntax - Markdown syntax supported by DITA Open Toolkit, which is the most commonly used engine for DITA publishing.
- MDITA Syntax - Markdown syntax for Lightweight DITA supported by DITA Open Toolkit, which is the most commonly used engine for DITA publishing.
- Pandoc’s Markdown - Markdown syntax of Pandoc, a universal document converter, which can convert between various formats.
- kramdown Quick Reference and kramdown Syntax - Markdown syntax of kramdown, which is the default Markdown parser for Jekyll.
If you want to explore more resources about Markdown, see Awesome Markdown.
reStructuredText
reStructuredText is a lightweight markup language that is more well-defined compared to Markdown and widely used for Python documentation.
If you are completely new to reStructuredText, the following 📔 introductions and tutorials are the best starting points for you:
- Introduction to reStructuredText
- A ReStructuredText Primer - Informal introduction to reStructuredText, authored by Richard Jones.
- reStructuredText Primer - Brief introduction to reStructuredText in Sphinx documentation.
Now, you know a bit about reStructuredText 👏. Just adopt a ✒️ reStructuredText editor, then you can try it out 🍧!
- Online reStructuredText editor
- Visual Studio Code (VS Code) - Code editor developed by Microsoft.
- reStructuredText - An extension to provide rich reStructuredText language support in VS Code.
- reStructuredText Syntax Highlighting - An extension to provide rich syntax highlighting and non-intrusive section navigation for reStructuredText in VS Code.
You may forget an infrequently used syntax or not sure about a specific syntax during writing. Pick a 📔 cheat sheet or reference documentation at hand, which you will look for sooner or later.
- Quick reStructuredText - Online cheat sheet for reStructuredText syntax.
- reStructuredText Cheatsheet - Downloadable two-page cheat sheet for reStructuredText syntax.
- reStructuredText Markup Specification - Detailed technical specification for reStructuredText, authored by David Goodger.
DITA
DITA is an open source standard for creating topic-based structured technical documentations, which was originally created by IBM and was donated to OASIS in 2004.
DITA was initially spread to high-tech companies like Adobe, Boeing, Siemens, and Nokia, and then become more and more popular in all industries.
If you are completely new to DITA, the following 🔔 courses and tutorials are the best starting points for you:
- DITA 101 Guide - Introductory document to DITA, produced by IBM.
- LearningDITA - Nine game-based courses for DITA beginners, developed and maintained by Scriptorium.
- DITA for the Impatient - Short DITA tutorial to teach the basics of DITA, developed by Hussein Shafie at XMLmind Software.
Now, you know a bit about DITA 👏. It’s time to practice 💃🕺!
That said, DITA is a bit complicated. Adopt a DITA-aware XML editor first, in case you are trapped in the tremendous DITA elements. Then, keep a 📙 book of DITA best practices at hand for reference at any time.
- DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA - A practical book about how to write effective technical information in DITA, published in 2011 by IBM Press (paid resource).
- The DITA Style Guide: Best Practices for Authors - Written in DITA 1.1 by Tony Self.
- Jorsek’s Technical Content Development Guide - Developed by the maker of Heretto CCMS.
- Oxygen XML Author使用指南 - A practical DITA migration guide in Chinese for technical documentation teams that are new to DITA and Oxygen XML Author.
You can use DITA to improve your own technical documentation. If you don’t have such resources, pick one of 📔 open source sample manuals written in DITA to see how it was written and think how to improve it.
- DITA Mini Manual - Mini owner’s manual that published in 1960s rewritten in DITA.
- Pilot Training Mitchell Bomber - A pilot training manual (aviation document) rewritten in DITA.
- LwDITA Code Samples - Various manuals of a 1970s computer rewritten in Lightweight DITA.
- DITA Glossary Example - A book named On Yacht Sailing rewritten in DITA to demonstrate how to implement glossaries.
- DITA Style Guide - Source code for The DITA Style Guide: Best Practices for Authors, written by Tony Self.
- BTS Manual - User manual of Berlin Text System written in DITA.
- DITA Open Toolkit Documentation - Source code for the DITA-OT documentation.
- Oxygen XML User Guide - Source code for the Oxygen XML documentation.
DITA has much more elements than Markdown and reStructuredText. If you encounter something unknown, resort to 📘 official specifications.
- DITA Version 1.3 - The latest official specifications for DITA, which was released on Jun 19, 2018.
- Lightweight DITA: An Introduction Version 1.0 - The Committee Note 02 for Lightweight DITA, which was approved on Oct 30, 2018.
If you like to stay current with DITA developments, visit the 📁 official repositories in GitHub often.
- DITA Specification - The official repository for the source files of the DITA specification developed and maintained by the DITA Technical Committee.
- Lightweight DITA Specification - The official repository for source files of the Lightweight DITA specification developed and maintained by the Lightweight DITA Subcommittee.
- DITA Specializations - The official repository for DITA specializations that were developed by the DITA Technical Committee, but are no longer part of the DITA standard.
S1000D
S1000D is an international specification for procurement and production of technical publications, which was initially developed for military aerospace industries and spread to various civil and military aero-amphibious equipments later.
S1000D is the most complicated standard for technical documentations. That means, there are rare free resources for self-study.
Here are the 📁 official specifications and implementations in specific industries.
- S1000D Specifications - All versions of official specifications for S1000D.
- ATA Spec 1000BR: Civil Aviation Business Rules for S1000D - An implementation of S1000D specification in civil aviation industry (paid resources).
- S1000D DIG Business Rules - An implementation of S1000D specification in the defense industry.
- The Shipdex Protocol: Issue 2.3 - An implementation of S1000D specification in the shipping industry.
Content accessibility
Developing content with accessibility in mind ensures that your websites, manuals or documents are meaningful and usable for as many people as possible.
Introductory materials
- Microsoft accessibility resources - Accessibility training courses, accessible design approaches and tools and other resources developed by Microsoft.
- IBM accessibility resources - IBM accessibility design tools, IBM Accessibility Requirements, Accessibility Conformance Report of IBM products, and other resources developed by IBM.
- European Accessibility Act: A Guide to Compliance - Explains the requirements in the European Accessibility Act that companies must comply with and the compliance deadlines.
- 信息无障碍研究会：无障碍生活指南 - Survey report on barriers to accessibility in our daily life, latest accessibility technologies and recommendations on further improvements.
Laws and regulations
- Americans with Disabilities Act of 1990, As Amended - Federal civil rights law of United States that protects people with disabilities from discrimination in everyday activities.
- Rehabilitation Act of 1973: Section 508 - Accessibility requirements for the federal government and all federal agencies of United States to use electronic and information technology.
- 美国508无障碍法案 - Chinese version of Rehabilitation Act of 1973: Section 508.
- Directive (EU) 2019/882 on the accessibility requirements for products and services - European Accessibility Act.
- Accessibility of products and services - Summary of European Accessibility Act.
- 中华人民共和国无障碍环境建设法 - Accessibility law in China which regulates the construction of accessible facilities, accessible information exchanges, social services, and so on.
Standards and specifications
- Web Content Accessibility Guidelines (WCAG) - International standard to make web content more accessible to people with disabilities.
- Authoring Tool Accessibility Guidelines (ATAG) - International standard for developers to make authoring tools more accessible to people with disabilities and more convenient to create accessible web content.
- User Agent Accessibility Guidelines (UAAG) - International standard to make browsers, browser extensions, media players and other applications more accessible to people with disabilities.
- Accessible Rich Internet Applications (WAI-ARIA) - International technical specification to improve the accessibility and interoperability of web content and applications.
- 信息技术：互联网内容无障碍可访问性技术要求与测试方法 (GB/T 37668-2019) - China’s recommended standard for the technical requirements and the conformance testing of web content accessibility.
Text processing
Equipping yourself with some programming skills will enable you to complete some really cool jobs, such as automating workflow and batch modifying.
Regular expressions
A regular expression (regex) is a pattern that the regex engine can use to find or match substrings. Regex is extremely useful in finding and replacing texts or strings in text files.
If you are completely new to regex, the following 📙 tutorial is the best starting point for you:
- Regular Expressions: The Complete Tutorial - Easy-to-understand and practical book for regex beginners.
Use an 💻 online tool to experiment the regex in the tutorial. It will make your studying easy and interesting.
- Regex 101 - Online tool to build, test and debug regexes.
- RegExr - Online tool to learn, build and test regexes.
[!TIP] You can also use a text editor with support for regex, such as VS Code.
Take a 📔 cheat sheet or quick reference at hand to check the regex syntax at any time:
- Regular Expression Language: Quick Reference - Quick reference for regex from Microsoft.
- Regular Expression Syntax Cheat Sheet - Cheat sheet for regex in the JavaScript Guide from MDN Web Docs.
XSL
XSL (Extensible Stylesheet Language) is a styling language for XML. It consists of three parts: XSLT, XPath, and XSL-FO.
XSLT (XSL Transformations) is a language for transforming XML documents. It is widely used in many purposes other than stylesheets, like transforming from one XML language to another, generating HTML pages from XML documents, etc.
- XSLT Tutorial - For XSLT beginners. It was developed by W3Schools.
- XSLT Version 2.0: Second Edition - The latest official specification for XSLT, released on Mar 30, 2021.
- XSLT Version 3.0 - The official specification for XSLT 3.0, released on Jun 8, 2017.
XPath (XML Path Language) is an expression language for navigating through elements and attributes in an XML document.
- XPath Tutorial - For XPath beginners. It was developed by W3Schools.
- XPath 3.1 - The latest official specification for XPath, released on Mar 21, 2017.
XSL-FO (XSL Formatting Objects) is a language for formatting XML documents. XSL-FO is also called XSL.
- XSL-FO Tutorial - For XSL-FO beginners. It was developed by W3Schools.
- XSL-FO Tutorial - Learn-by-example tutorial for XSL-FO beginners. It provides a series of examples working in XEP.
- XSL Version 1.1 - The latest official specification for XSL-FO, released on Dec 05, 2006.
PowerShell
PowerShell is a task automation tool from Microsoft, which is built into all versions of Windows.
- PowerShell 101 - Book for PowerShell beginners. Its content is open to public by Microsoft on its website.
- Everything You Want to Know about … - A series of articles about PowerShell, collected from the PowerShell Explained blog by Microsoft.
- PowerShell Documentation - The official documentation for PowerShell 7.4.
If you like to explore more resources about PowerShell, see Awesome PowerShell.
Version control
- Learn Git - Short tutorial to teach Git basics, by Microsoft.
- Pro Git - Complete and practical textbook with graphic illustration to teach Git fast and well (available on the Git website).
- Git Cheat Sheets - Cheat sheets of common Git commands in 20+ languages, by GitHub.
- Git Cheat Sheet - Visualized cheat sheet of common Git commands.
- Git Reference - Official reference manual of Git.
Knowledge sharing
More and more professionals are sharing their invaluable experience and professional insights online, and so do technical writers. Let’s learn from others!
Blogs
- I’d Rather Be Writing - Tom Johnson, a technical writer at Google, writes about API documentation, AI, and other topics about technical writing.
- DITA Writer - Keith Schengili-Roberts, a senior manager for technical documentation at AMD, writes about DITA and technical writing community.
- Just Write Click - Anne Gentle, the director of developer experience at Cisco DevNet and the book author of Doc Like Code, writes about her books, interviews, experience and insights about technical writing.
- Everything Technical Writing - Linda Ikechukwu, a technical writer transitioned from a frontend developer, writes about what she learned and experienced as a technical writer in the software industry.
- James’ Coffee Blog - James Gallagher, a technical writer at Roboflow (a computer vision startup), writes about her daily work as a technical writer.
Podcasts
- Write the Docs Podcast - Discussions related to software documentation between members of the Write the Docs community.
- I’d Rather Be Writing Podcasts - Tom Johnson, a technical writer at Google, records his interviews, presentation recordings, individual monologues, etc.
Professional communications
Join a live talk or an in-person presentation to connect yourself with your peers from all over the world.
Webinars
- The Content Wrangler - BrightTALK channel for content management, with more than 70k subscribers.
