My Dream Documentation System

writing

I have been thinking about writing documentation for a software project, but none of the existing systems that I know handle my use case. At the same time, I've been thinking of reworking my blog and I would like a better Emacs/org-mode workflow. Having a system will allow me to be consistent across all of my projects would mean I could create some Emacs keybindings. This could potentially be fully developed into its own product.

Use Case

For the last year I have been helping to productize a research code. This project should have many kinds of documentation:

  • Doxygen for browsing the code [audience: developers].
  • Web-based documentation, with the option to see documentation from the latest features [audience: existing users].
  • Multiple LaTeX generated PDFs (for user and developer manuals) [audience: newbies].

Requirements

  • Markup Agnostic: I would like my (unenlightened) colleagues to use this system as well. Meaning, it should support any markup language they choose.
  • Multiple Output Formats: I would like generate both web-based documents as well as LaTeX generated PDFs.
  • Simple Organization: The small pieces of documentation should be easy to organize into multiple, larger documents. Not only could users see the documentation in a prescribed hierarchy, but as list of "latest" new features. This would also allow for separate developer and user documentation. One issue here would be ensuring that each headline in the resultant documents is at the right spot in the hierarchy.
  • Simple to Deploy: The generated documentation should exist both as source code and as deployed content. The deployed content should be updated every time the source is updated.
  • Simple Software Stack: I want new users to see the power of this system without having to install a huge software stack on their system. Particularly, I teach a ton of undergraduate students who have to use Windows machines (and often don't have root). Thus, each piece in the software stack should be easy to install.

The input/output agnosticism leads me to believe that pandoc is the way forward.

Workflow

  1. Content lives in source code branch under docs/. There are some-sort of specification files which describe the various documents and their contents / hierarchy.
  2. Generation and deployment happens through Travis (or some other CI). The deployed documentation is automatically updated when the source is updated. This deployment could be replicated locally through git work tree.
  3. Deployed documentation lives in a different branch (e.g., gh-pages). The goal is that documentation contributors never have to deal with this branch. In theory, I can assume that there is only 1 website output.

Question: Styling

This raises one question: Where do the styling assets live? Also in the /docs source code? I really like the way the Jekyll handles this.

I think the right answer is that styling information lives in the branch. Designers work on the branch, content development works in source. Plus, there can be as many branches / output documents as you need. But, having to checkout the particular branch to do the styling will probably be confusing.

Setup

docs/
 |-- content/
 |   |-- images/
 |   |   `-- overview.png
 |   |-- group1/
 |   |   |-- feature_a.md
 |   |   `-- feature_b.org
 |   `-- feature_c.rst
 |-- gh-pages/
 |   |-- TOC
 |   `-- CONFIG
 |-- doxygen/
 |   |-- Doxyfile
 |   `-- CONFIG
 `-- user-manual/
     |-- TOC
     `-- CONFIG

Each sub-folder (other than content) is the name of a branch. My system will do something smart with git work tree.

Each output will need know 2 pieces of information:

  1. The order in which the content should exist. Side note: to fully support date-ordering, each piece of content must have a date.
  2. Some (as of yet undefined) configuration settings. Perhaps this includes details on how to deploy?

This information should exist on the source branch. There will have to be some really smart .gitignore files as well.

Needed Functionality

Just looking at the setup, there are number of details that need to be right.

  • Setup Project
  • Add New Output
  • Deploy all

Conclusion

This sounds like a cool new project! I hope I can find some time to work on it.

Comments

Comments are sent directly to me and may or may not be posted for display on this page.