Top tools for a Technical Writer
When you are working with content on a daily basis, probably you already have a list of your favorite apps, tools, and services that allow you to work faster with texts and documentation. That's great! But chances are that this list is not perfect. "Fast" is not always equals "efficient".
Sometimes, when you urgently need a new tool for a specific purpose, you just type your search request and then choose the "most relevant" app from the top of the search results. Regardless of its usefulness, this app tends to stay in the favorites forever. As practice shows, this is rather an inefficient method.
This was my case previously. But now, I'm always trying to take some time to compare my new apps with some alternatives and find out whether my choice is the best one. Kind of trials and errors. This is, actually, the way how this list appeared. So, let me share my thoughts on what apps, tools, and services a seasoned Technical Writer must use. Or at least try.
Writing Tools
Like this appProbably the best documentation writing format ever made. With a countless number of features out-of-the-box (with the greatest ones, like sections re-usage, source code inclusion, dynamic variables), Asciidoctor sets a new standard of how technical documentation should be written.
- Free • Open Source
- Mac
- Windows
- Linux
- Online
- Self-Hosted
Like this appMarkdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
- Markup Language
- Free • Open Source
- Mac
- Windows
- Linux
Like this appSphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.
- Documentation Generator
- Free • Open Source
- Mac
- Windows
- Linux
- Python
Like this appFast and intuitively simple code editor with lots of handy tools out-of-the-box. I've been using VS Code since late 2015 and this is a really great experience.
- Code Editor
- Free • Proprietary
- Mac
- Windows
- Linux
- Online
- Chrome OS
Auxiliary tools
Like this appI use Simplenote when I urgently need to jot down quickly some information and there is no pen/notepad at hand.
What makes Simplenote perfect for me:
- electron-based app with simple and clean UI.
- just a single click to create a new note. No titles, no categories, no other required fields. Click and start typing your note.
- auto-save as you type. Say "No" to unsaved/lost changes.
- instant search. You are a few symbols away from the note or text you are looking for.
- sync. Two-way cross-platform sync. So your notes are always up-to-date on any device.
- markdown support with preview. Probably the best usage of Markdown is for taking quick notes. Simplenote supports Markdown flavor similar to GitHub, so you can use checkboxes (e.g. for todo lists), emoji, tables, etc.
- sharing functionality. You can either add collaborators or share a particular note with the public link.
- history of changes with immediate restoration of revisions.
- pin important notes to top.
- configurable UI view, theme, and sort order
- trash bin. If you unintentionally deleted a note, you can restore it later.
- export. During the export, all the existing notes are saved in .txt format and then archived. words/characters counter. It is useful sometimes.
- Note-taking Tool
- Free • Open Source
- Mac
- Windows
- Linux
- Online
- Android
- iPhone
- Android Tablet
- iPad
Like this appExcellent tool for making screenshots on-the-fly. Lots of configurable settings, post-editing capabilities, uploading sources, and plugins. The only disadvantage - it doesn't support the entire page screenshot (like in Nimbus), only visible part of the screen.
- Screenshot Capture Tool
- Free • Open Source
- Linux
Like this appWhat could be better than one Terminal? Only two Terminals in one window... or three... or as many as you need, arranged in the order that makes you comfortable to work with these consoles.
- Terminal Emulator
- Free • Open Source
- Linux
- BSD
- GNOME
Like this appMy job is not always writing. Sometimes I need to create graphic content, like BPMN, UML or just simplified workflow diagrams to provide users with better understanding of some technical aspect or feature. draw.io supports lots of diagram types and the final sketch can be easily exported to any format you want (including XML, HTML, PDF, JPG, PNG, and SVG) It is a perfect tool to create a technical drawing of any complexity.
- Diagram Editor
- Free • Proprietary
- Mac
- Windows
- Linux
- Online
- Chrome OS
- Notion
- Self-Hosted
- Microsoft SharePoint
- Microsoft OneDrive
- PortableApps.com
- Google Drive
- Google Docs
- Microsoft Teams
- Google Slides
- Google Sheets
Like this appI tried many Git clients out there (however, I still use Terminator, as the most convenient one :)) but GitKraken is the only one I use from time to time to bring branch chaos into order in some of my personal repositories.
- Version Control System
- Freemium • Proprietary
- Mac
- Windows
- Linux
- Visual Studio Code
- Online
- Google Chrome
- Firefox
- Microsoft Edge
Like this appI use Caddy when I need a quick preview of some html files. Caddy is ready to serve your site in 1 second, it has flexible configuration options, HTTPS, hot reload and lots of plugins to extend server configuration. Why should you look for something else?
- Web Server
- Free • Open Source
- Mac
- Windows
- Linux
- BSD
- FreeBSD
- OpenBSD
Static Site Generators
Like this appThe best documentation generator for OpenAPI Specification (Swagger). It is under continuous development, so new features appear on a regular basis.
- Free • Open Source
- Online
- Self-Hosted
Like this appA static site generator for creating documentation sites from AsciiDoc content aggregated from multiple repositories. Made by the creators of Asciidoctor.
- Documentation Generator
- Free • Open Source
- Mac
- Windows
- Linux
Like this appMkDocs is static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.
- Documentation Generator
- Free • Open Source
- Self-Hosted
- Python
Like this appDocumentation generator for JavaScript.
- Documentation Generator
- Free • Open Source
- Windows
- Linux
- Self-Hosted
