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
Probably 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.
Markdown 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).
Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.
It was originally created for the Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well.
Fast 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.
Auxiliary tools
I 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.
Excellent 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.
What 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.
My 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.
I 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.
I 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?
Static Site Generators
The best documentation generator for OpenAPI Specification (Swagger). It is under continuous development, so new features appear on a regular basis.
An Asciidoctor documentation toolchain that helps technical teams create, manage, collaborate on, remix, release, and publish documentation sites sourced from multiple versioned repositories.
MkDocs 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.
A good documentation generator for JavaScript.
Features:
- Documentation coverage measurement
- Documentation lint
- Test codes integration into documentation.
- Integration of manuals into documentation.
- Parse ECMAScript proposals.
- Custom features via installable plugins
- ESDoc Hosting Service
