4 tools technical writers use
We polled a community of technical writers for different ways that authors write with digital tools.
Technical writers have their choice of tool to use when creating documentation, from markup systems to content management platforms to desktop applications. We polled a community of technical writers for different ways that authors write with digital tools, and found these four themes:
Lightweight markup
Technical writers love to use lightweight markup formats to create documentation. Using a formatting system like Markdown, Asciidoc, or reStructured Text, an author can focus on the content and not how it will look.
For example, consider this sample document written in Markdown. The “double underlined” text indicates a top-level heading, the * around text indicates italic text, and ** creates bold text:
Document title
==============
Writing content in Markdown is easy. With Markdown, I can
focus on the **content** of what I'm writing, and not get
distracted with *what it will look like*.GitHub and GitLab both support Markdown documentation files by default. This makes it easy for any technical writer who is embedded with an engineering team to use “Docs as Code” to create and maintain document. Google Docs also supports Markdown, both while writing a document in the editor, and when importing a new file into Google Drive.
To learn more about using a lightweight markup system like Markdown, start with the Markdown Guide or the interactive Markdown Tutorial.
HTML and CSS
These days, most content is destined for the web. And while technical writers rarely write HTML “from scratch,” it’s important for writers to know how HTML and CSS work. When importing content into a web content management system, a document might require additional formatting that the website’s stylesheet doesn’t support. If the technical writer understands how to use HTML and CSS, they can use Source View in the content system to add direct styling, such as style="border:1px solid lightgray; margin:1em; padding:1em;" to add a light gray border around a block of text.
Very rarely, a web content writer may need to dig into the HTML on a website to fix something at a low level. Other technical writers said that they sometimes create mockups of new websites using very simple HTML. Again, knowing the fundamentals of HTML and CSS make this an easier job. Consider this minimal but technically valid HTML document:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Document title</title>
</head>
<body>
</body>
</html>To learn more about HTML, start with the HTML overview at Mozilla’s excellent online resource. Also consider W3 School’s free HTML Tutorial.
Word processors
The desktop word processor is still a daily driver for many technical writers. But the landscape is shifting here; where Microsoft Word used to dominate the landscape, more technical writers are shifting to Google Docs for the ease of collaboration, or to Canva for one-off products like fliers and information sheets, or LibreOffice Writer for the flexibility in formatting complex documents.
To leverage the power of a desktop word processor, the folks we talked to recommended using styles for everything, and modifying the styles to do what you need to do. For example, LibreOffice provides fine detail in formatting with styles, giving direct access to paragraph styles, character styles, table styles, and page styles. In LibreOffice, use the Styles>Manage Styles menu to bring up the Styles menu where you can apply and modify the styles for your document.
Text editors
When not using a word processor, many technical writers rely on a text editor. This is more than the simple Notepad app in Windows. Technical writers prefer a programmer’s editor like Visual Studio Code, Notepad++, or Sublime Text.
Bonus: Conversion tools
Several technical writers we spoke to highlighted pandoc to convert files from one format to another. pandoc is a powerful tool, and can convert between lightweight markup formats like Markdown or Asciidoc, HTML, word processors like Word DOCX and LibreOffice ODT, wiki markup including MediaWiki, and scientific markup such as LaTeX and groff.
While using a command line tool like pandoc isn’t a necessity, technical writers who understand how to navigate the command line, such as to use pandoc to automate tasks, often find themselves in high demand.
Technically We Write is a community of technical writers, technical editors, copyeditors, web content writers, and all other roles in technical communication. We'd love to share your story! Contact our editors to share your article idea.