Mike Hamrick has put up an excellent video on using Emacs and Org-mode to publish nice looking and consistent technical documents. In preparing a document, Hamrick uses literate programming and—although he doesn’t mention it—reproducible research techniques. That’s important, because as he notes, if the code or data used in the document changes, things that depend on that code or data will change as well and it’s important to keep them in sync.
This is exactly the problem—or at least one of the problems—that Org-mode’s Babel was designed to solve. By having Babel embed the results of running the document’s code against its data into the document itself, you’re guaranteed that everything will stay consistent.
Hamrick has a few tricks that he uses to get a nice looking document and keep it consistent. For HTML, he uses Fabrice Niessen’s ReadTheOrg theme, which I’ve written about before, to produce beautiful HTML documents. The other trick he uses that I really liked is to have a file of helper functions that he can call from the text he’s writing. These do things like return the length of a string or the first 2 characters of a string. By using them, he ensures that his document remains consistent even if the data the string is from changes.
Don’t worry about trying to absorb the source code from the video. He’s put all the code and data for the video on GitLab. Similarly, his configuration files are on GitLab so you can see his publishing setup.
The video is 22 minutes, 42 seconds long so you’ll need to block out some time but it’s very much worth it. If you use Org-mode in your writing, you really need to watch this video.