Comparison and Recommendation of Document Tool Chain

I'm a developer/technical writer who worked on the DCAE team within AT&T last year. I redesigned a documentation system that produces the DCAE Deployment Guide that we're hoping to open source soon. The team faced several challenges that the documentation system – tentatively called "MkTechDocs" – solved.

1. I was the only technical writer on the project. DCAE is a very complex system, composed of many different moving parts. Our documentation system allows developers to contribute documentation in support of their components via Git pull requests, which I then proof/change and merge into the documentation repo. It scales well and makes it easy to keep documentation up to date since the developers only need to make incremental changes in Git, which they're all using anyway. (As opposed to editing Wikis, which, in my experience, go stale often.)
2. Parts of the documentation used live Java code that was part of DCAE to produce documentation, so MkTechDocs contains Java hooks via Groovy to allow for using pre-existing Java libraries. Groovy's template system is also quite powerful, as it allows us to do things like iterate through configuration files for the purpose of documentation. Python is also supported, as are Python templates via Jinja2. These are baked into the core of the system, so using them is as easy as creating a correctly named file (e.g. mycomplexdoc.gt, mycomplexdoc.py).
3. Support for PlantUML diagrams.
4. The DCAE Deployment Guide has historically been a PDF, but the documentation system needed to be able to easily produce different formats. Ours currently does markdown, PDF, Word, single-page CSS-styled HTML, multi-page CSS-styled HTML, and potentially many other formats.

MkTechDocs is 100% open source. It's standardized around GNU Make, Markdown (because most developers already know it), and pandoc. At its heart is a small set of document transformation pandoc "filters," which manipulate pandoc AST in order to maintain consistent heading levels across multiple markdown documents, fix internal document links, allow for infinite recursive includes, syntax highlighting, UML diagrams (via PlantUML). It could also fit nicely into a CI toolchain since builds can be triggered.

We're hoping to release it as open source soon, at which time the documentation (created with the system, naturally) will be available to check out.

I think it might be worth considering given that it's been used now by the DCAE team for a year or so.

Hi James  --

Yes, MkTechDocs uses Markdown. However, the system is flexible enough that it can use other formatting syntax that pandoc can understand. What's interesting is that using my system, a team who has already standardized on Textile, for example, could use that if they wanted. It was designed from the ground up to be as flexible as possible since we thought that was the best way to encourage busy developers to actually document their code , by making it super easy to do so. Then, we technical writers can edit and proof it for consistency and grammar, etc.

I have also worked with another team at AT&T for a while, RCloud, who also uses Markdown and make. I have concluded that many people use a similar technique to build their documentation. The difference with my system is that I've completely abstracted the build system away from the project so that it is easily distributed. I.e. it is project agnostic and easily configured for basic setups.

I will post a link to the repo whenever it goes public.

Spence

I'm a developer on the DCAE team and for the DCAE platform documentation, we used Mkdocs and published on Github pages. Good documentation is very important but is always been a hassle for developers to maintain and keep up-to-date. Keeping the documentation easy by using tools that developers are already familiar with is important to lower the obstacle. For me Mkdocs provided the best, easiest experience compared to Hugo and to Jekyll particularly the integration with Github pages. Mkdocs focus is on building documentation websites unlike Jekyll and Hugo.

I would also advocate for Sphinx and rst because of its wide adoption with the Python community and because of its focus on building documentation sites.