JTR over at The Art Of Not Asking Why has an interesting post on how how he writes instruction manuals. The post was in response to a question from someone on Reddit.
As for Org Mode itself, he doesn’t have a lot to say. He sets some metadata to get rid of the table of contents, enable inline images, and turn off section numbering. He also sets org-export-with-broken-links to t so that he can still export his document even if the link has changed. He doesn’t worry about the links until it’s time to publish because—in his environment—they tend to change often.
JTR uses Denote as a sort of front end to Org Mode. He uses some of its features to organize and associate his files and to keep track of when they were written. He also uses Pandoc for export because of its support for Word templates. Again, that’s something required in his environment.
The rest of his post talks about the procedures he uses for writing his documentation. For example, he uses the Microsoft Style Guide—even though he doesn’t like Microsoft—because it ensures consistency in his documents and because most of his users are on a Microsoft platform.
Interestingly, he’s parsimonious with the depth of his sections. He feels that a depth of more than two is an indication of an overly complicated set of instructions and a signal that they should be rewritten.
One thing I learned from his post was the use of target=blank (target=_blank is probably better; see this post for the difference) to force a link to open in another tab. Sadly, Org Mode does not have support for this so you have to add it manually.
If you have to write documentation and you’re an Emacs user, take a look at JTR’s post. It may have some useful ideas for you.