Palabra
Technical
With the range of software documentation tools available it’s difficult to know where to start.
I recently compared available documentation tools to determine which are best suited for a project I’ve been working on. What follows is a summary drawing from my own practical experience working as a technical writer while considering perspectives of others working in the field.
My recent presentation at Université Paris Cité International Conference on Technical Communication discussed technical documentation as an aesthetic.
Aesthetics is most often associated with cultural phenomena such as art, music, fashion, and film. However, we can consider the term more broadly.
Technical writers and communicators are creating artefacts that reflect sophisticated products and technologies. These artefacts are often the result of collective efforts of many talented people. A challenge is designing documentation that reflects this sophistication while keeping it accessible for end users.
A challenge of maintaining docs-as-code is organizing comments and feedback.
It is inconvenient for team members to download a repo and comment directly in the markdown. Tools for commenting directly in the browser can be hit-and-miss. Besides, team members will appreciate using familiar tools rather than introducing new ones.
A solution is Pandoc to convert markdown to Google docs. This article will show simple shell scripts to bulk convert markdown files for Google Drive.