Org Template for Specification Documents

Karsten Schmidt published a really nice template for producing great looking specification documents. The result looks like this. Here is the Org document that produced that output. The whole project, including the CSS style sheet is on GitHub.

You may or may not be interested in producing specification documents but the template is valuable regardless because of the many techniques that it demonstrates. For example, the Changes since last version section is generated automatically from the git commits since the last version.

All the diagrams are generated on-the-fly using Org-babel. One nice feature is that the styles for the diagrams are specified separately from the content of the diagrams using literate programming techniques (see the Diagram definitions section in the Org file). That means that if you have multiple, say, dot diagrams, they will all have the same style features and that if you want to modify the style you can do it in one place for all the graphs.

If you read the exported HTML document along side the Org document carefully, you will almost certainly learn some valuable tricks. If your CSS skills are as poor as mine, reading over the style sheet will also show you some nice techniques.

The template puts me in mind of the AT&T memorandum cover sheet that Troff produced (here’s an example). All that boiler plate on the first page is generated automatically much like a great deal of Schmidt’s document is generated automatically from the input text. You can easily adapt this template for use in whatever recurring documents you produce so it will more than repay the study you devote to it.

This entry was posted in General and tagged , . Bookmark the permalink.