On Reddit, someone asked how to write software documentation in org-mode, and I had a lot to say. Reddit, being Reddit, however, wouldn’t let me post my long comment. That’s fine, I don’t like spreading knowledge in silos anyway.

Here’s what I said:

Hi, my job involves writing technical documentation (instructions mostly), and I use org-mode for it all the time. I polished my process over the years, and it’s a loooong answer to a lot of stuff you probably didn’t ask, but I’ll try to break down the major parts.

First, I use Denote to write all my documentation, one file per tool or procedure if possible. Denote allows me to auto-associate files with keywords (for example, instructions for macOS vs Windows) and also shows me when I wrote the file automatically (it’s in the file name), so I know how old the information is. In the org-mode file itself, I often add notes using C-c !, an inactive timestep, so if there’s an update to a part of the instructions, I know what happened when. Something I don’t use for work but in my own notes is Denote’s dynamic blocks (a block of code with dynamic links to other org files), which serve as an index to quickly view related notes.

In the org-mode file, besides the Denote options, I add options in the meta part to get rid of TOC (table of contents) and display images inline: #+STARTUP: inlineimages and #+OPTIONS: num:nil. I often use annotated images, which I embed into the org file and attach to the headers (so the images are connected to the files).

A couple of years ago, I decided to adopt and use the Microsoft Style Guide (look it up, see if it’s for you) mostly to keep consistent. I don’t like Microsoft, but they have some documentations that make sense, and my work environment is Windows-based, so they cover what I need. There are other style guides out there; whatever you find, stick with it. The style guide is what tells you what words should be in bold (UI elements and buttons) vs what gets italicized (things you want to emphasize) or why you should use “select” over “click” or “tap” (because it’s more generic and applies to more UIs). It’s up to you how crazy you want to get. I find that it helps immensely, and it’s already become an integral part of my writing.

When I write in org, I often use comments (# followed by a space and the comment) as a reminder of what I still want to cover as ideas come to me under the paragraph I’m currently writing. For example, in this long post, I had a # what about images? under what I was writing until I got to it as a reminder.

I don’t use headers right away, unless it’s something obvious from the start, like an Introduction explaining what a certain tool is (first header) and then the process to use it (second header). I prefer numbered lists and quick steps in my instructions; each line describes one action, unless it’s something simple. I use links often - and here’s another important tip: I have (setq org-export-with-broken-links t) in my settings because org-mode expects nice normal links, but Microsoft products don’t always have them, and org-mode won’t let me export with what it considers broken unless I turn it off. I validate links later, in the finished product (by the way, always use target=blank in your links so when someone selects a link, it doesn’t hijack their window but opens another window or a tab).

I don’t use in-document links (anchor links, forget what they’re called) because these don’t always work well. It’s better to tell your users something like “for uninstall instructions, see header name below,” and let them go there. Anchor links are confusing and can break when you export.

When I’m done with my lists, I see if the sections make sense. I sometimes break into sub-sections, but if I go beyond 2nd level headers, I need to consider if I should expand into another article because it tells me the instructions are getting too complex.

I got to expand a bit more about Images. Using images is almost always better, as long as they are clear and use consistent annotations (write your own style guide). I prefer arrows over circles because I find they draw the eye better, and I like using callouts with text (like in speech bubbles in comics), pointing to what I’m talking about in the images. I try to use the same text from the instructions in the images. So if step 3 in the instructions says “select submit,” I will use a bubble pointing to that button in the image, and it will say “select submit” exactly the same way. There’s more to say about images, but this goes beyond org-mode, so I’ll stop here with this.

When I export, I use pandoc . I don’t like to use Emacs HTML exporter. The reason for that is that pandoc comes with more options and the ability to have a “template” Word document that will automatically stylize your document with the right colors, font, font sizes, etc. You tweak it once in Word and it’s good forever. I don’t like to use html from org-mode because it comes with a lot of extra “fluff” you need to strip away (it’s possible, you need to find the options in the Emacs manual and specify, I just got lazy), and also everyone at my workplace uses Word or SharePoint, so it’s just easier. I love Pandoc, and I highly recommend looking into it if you’re writing a lot.

I can keep going… There are spell checkers and grammar checkers (not the same thing), and Emacs doesn’t really have a good built-in grammar check, in my opinion. I blogged about Harper not too long ago, and it’s a good tool that can be integrated into Emacs (especially if you’re on a Mac), but if you’re writing for large audiences, you might need something better. There’s more to say about videos vs images, and depending on what system you store your articles in, it affects what you want to do there (or don’t want to do there), as in if it’s a wiki or a ticketing system or some other content management system.

But it’s time to grab some dinner.

If you have specific questions, feel free to ask. I love talking about these things if it’s not obvious!