Awesome Technical Writing Learning Awesome

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

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:

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 😄!

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 sytle guides are or why you need one, go back to Google Technical Writing Courses for Engineers for a refresher.

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.

Dictionaries

And you know, select a suitable 📘 dictionary too!

Now, you can use the writing skills to improve your own technical documentations!

Technical illustrations

A picture is worth a thousand words.

High-tech industries usually rely heavily on technical illustrations in their technical documentations, such as manufacturing, automotive, aerosapce, and defense. But unfortunately, there are few resources available 🤓.

Technical illustrators used to use software like Adobe Illustrator or CAD to create technical illustrations. But now, 💻 softwares specially made for technical illustrations are becoming more and more popular.

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:

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 new 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 extentions.
    • 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 extention to generate Markdown tables in an easy and intuitive way.
    • Markdown PDF - An extenstion to convert Markdown files to PDF, PNG, JPEG, or HTML.
    • Markdown Preview Enhanced - An extention 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 untill now. The Markdown syntax in each parser is to some extent different from others.

As a result, every time you choose a new Markdown tool, you had better read through its 📙 user manual or documentation to know exactly what Markdown syntax it supports.

If you like 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:

Now, you know a bit about reStructuredText 👏. Just adopt a ✒️ reStructuredText editor, then you can try it out 🍧!

You may forget an unfrequently used syntax or not sure about a specific syntax during writing. Pick a 📔 cheatsheet or reference documentation at hand, which you will look for sooner or later.

DITA

DITA is an open source standard for creating topic-based strcutured technical documentations, which was originally created by IBM and was donated to OASIS in 2005.

It was initially spread to high-tech companies like Adobe, Siemens, and Kone, 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:

  • 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.

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 has much more elements than Markdown and reStructuredText. If you encounter soemthing unknown, resort to 📘 official specifications.

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.
  • Leightweight 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 aeroamphibious 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.

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. Regexes is extremely useful in finding and replacing texts or strings in text files.

If you are completely new to regexes, the following 📙 tutorial is the best starting point for you:

Use an 💻 online tool to experiment the regexes 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 regexes, such as VS Code.

Take a 📔 cheatsheet or quick reference at hand to check the regex syntax at any time:

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 tranforming 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.

XPath (XML Path Language) is an expression language for navigating through elements and attributes in an XML document.

  • XPath Tutorial - For XPath beginners. It is 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 lastest 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.

If you like to explore more resources about PowerShell, see Awesome PowerShell.

Yedda Wang

Yedda Wang

If you like this list, feel free to leave a star on my GitHub repository. :-))

Wechat Subscription Account

Wechat subscription account ID: docSimpo

Scan the QR code to follow my Wechat subscription account (ID: docSimpo).