Technical Documentations Thoughts

A few weeks ago, I briefly mentioned I’m getting into technical writing at work. This has been an interesting experience. The following are some thoughts and general strategies I’ve been utilizing.

mored

I discovered that technical writing at work uses the “energy bucket” as most of my writing on this blog. It’s not that both are identical: the articles I write at work cover different subjects and they end up looking different than what ends up on TAONAW. Still, I feel I scratch my technology-writing itch for that sort of writing more often than not¹.

It was clear from the start: when it comes to writing and technical writing in particular, I was going to use Emacs and org-mode. The habit is ingrained too deep to consider anything else, and besides, it’s org-mode that gave my wiki-related writing the boost I need to produce my thoughts in a clear, concise manner.

The first thing I did was to make sure I have a template for the outline I needed:

* %^{Title}
%^{KB}p

** Introduction
** Requirements
** Process

Pretty straightforward:

1. Prompt for a title
2. Prompt for the KB ID number, place as property
3. Create a heading for the introduction
4. Create a heading for the requirements
5. Create a heading for the process

The introduction is for IT personnel to get a quick idea about the article they’re looking at before committing to reading it. I try to keep it as a sentence or in a few bullet points if it’s a complex process.

The requirements specify hardware, software, and knowledge required to follow the instructions. Since I cover many different articles, this can range from “have an adapter with a registered MAC address” to “have written permission from the HR department.”

The process is where I write most of the text. Usually, these are numbered lists (these can break down to further numbered lists) which include step-by-step descriptions with annotated screenshots. There are quite a few things to expand on when it comes to writing the process, but these deserve a separate post. I hope to expand on them later on.

Besides saving me time, the template also keeps me in check and reminds me of the proper workflow. Now and then I find myself starting to explain something I do at work, and then I get this nagging feeling of “this should be written in the wiki.” Thankfully, because Emacs is right there showing me my agenda, this is a seamless process.

This is one of the rudimentary yet genius things about Emacs: you probably already use it for something, so switching quickly to write a note about what you’re actually doing is as quick as thinking it. I can’t tell you how many ideas I’ve lost before I started to use Emacs simply because explaining what I’m doing meant I had to open another program, create a new note there, give it a file name, then save and get back to what I was doing. This is how good thoughts die, lost without the chance to be remembered.

When I’m done with an article, it’s time to export it out of org-mode. I found that the best way to handle that is to export the article I work on to HTML from within Emacs. I copy-paste the HTML after I open it in a browser and tweak up the formatting there. This usually includes uploading the screenshots and placing them at the right place in the article while deleting some comments Emacs still adds at the end, like the option to verify the HTML code.

Exporting this way also gives me a slight “bonus”: table of contents. The TOC provides a quick list of the headers and the subheaders at the top of the article, allowing others to jump to the right point in the article without scrolling, and the ability to store the exact location of what they need as a bookmark. This can be very handy, especially in a long article.

Yet another Emacs bonus: footnotes. The footnotes are exported with the links tying them back to where they’re announced in the article. This way I can expand on certain items and link to extra information if needed. Since I include footnotes in its own header (like in this post), it is also available from the TOC at the head of the article. Everything is delivered with one simple export to HTML.

With Emacs org-mode at my disposal, I get to extend my knowledge in my wiki to the rest of the team easily. Whatever I write is stored in my ownwiki as well as on the team’s database. I have my org files and they have their HTML exports. It’s a win-win.

Footnotes