For the last few weeks I have been working exclusively on the RhodeCode Enterprise and RhodeCode Control documentation. It’s a work in progress but quickly expanding to cover the full feature set available within both tools.
As part of building up a documentation set I investigated a number of different tools for the task and created a list of the basic criteria needed. What follows is essentially a break down of my review process.
Documentation Tools Criteria
Single Sourcing
Single sourcing is a very simple concept. You have certain files in which you define product names, generic notifications, and other very repetitive part of the documentation and you set their substitutes to be used throughout the documentation. The advantages of this are:
- Renaming a product, or tweaking a particular wording, is a one line change that can be propagated to all files. This lets me quickly regenerate new docs and immediately update any public facing information, greatly reducing the maintenance burden.
- Increased consistency. I’m aiming to have the same, correct, and accurate information every time for a particular item. Single sourcing is going to help me with this as I build, refactor, tweak, and proofread.
- Laziness, the fact that I created and know all the substitutions allows me to create docs much faster with minimal repetition.
- If someone else takes over the docs they will have a much easier job in tracing changes that need to be made if that situation occurs.
Multiple Output
Users want documentation in different formats depending on their preferences, or even internet access. Sometimes a very security conscious organization cannot access the internet so PDF documents need to be supplied. There is also the fact that people now consume material in many different formats (Epub, HTML, PDF, XML), and users need the docs in their native language. Sphinx allows me to create our documentation in these different formats, and to also export translation builds using gettext.
Note: I know I have not delivered these yet, but they are in my backlog awaiting prioritization. So if you are a user and need them, let me know as I have tested locally.
Topic Based Writing
Topic based writing is also a fairly simple concept. You keep each topic in a different file and when the time comes to publish you bring them all together using map file. In DITA you use .ditamap and .ditaval files, and in Sphinx you use the index.rst as the map file, and a combination of the conf.pyfile and directive for the equivalent .ditaval functionality.
This allows me to include topics that are ready, and drop those still in draft mode. With Sphinx I do not have to delete or move them out of the directory if it’s going public facing. The trick here is to use the exclude_patternsproperty in the conf.py file to ensure that the files specified do not get generated and leaked as standalone HTML output.
Cross Referencing and Hyperlinks
Any useful doc set needs to enable the user to navigate, find, and quickly absorb the information they need. The real issue is that no one actually RTFMuntil they have a problem, so as the creator you should expect that your user is on edge, trying to find a quick fix, 10 minutes before wanting to log off and hit the weekend!
Therefore, you need to cut the bull and deliver the information, and a big bold warning if it’s necessary. If this can be achieved in under 15 words, then all the better!
Cross-referencing really helps in this regard and lets you guide the user directly to the information they seek. Sphinx excels here, and I much prefer it to DITA. When you create a topic you can add a reference to it using the following example. Here the .. _api: acts as the anchor, and you simply reference that when you want to cross-reference. One nice advantage here is that it picks up any title changes, meaning your links are not broken when changing the wording.
.. _api: API Documentation ----------------- To see more, read the :ref:`api`.
Ease of Deployment
Sphinx builds really quickly, and you can do it locally, or hook it up with
Jenkins. This means is can be ready to deploy after every push, allowing you to quickly
catch any typos or awkwardness which can only be really caught when you read
something in a different setting than you write. Currently our docs are being
built in a constant ready to deploy state and I am pushing small updates
daily.
Extensions
Added functionality such as syntax highlighting, search, graphs, or video
plugins are becoming more important for delivering technical documentation.
One of the nice things about Sphinx is the ability to integrate these
different media formats into the documentation. Once again, these I have only
tested locally, and I plan to get more of this kind of content into the doc
set where it adds value for the user.
Customization
As a company, branding, marketing, and PR trickle into the engineering
department with varying degrees of comprehensible logic. The ability to
customize the image the documentation projects was also a consideration, and
so the static HTML output of Sphinx is perfect for this as you can leave your
design and CSS people knock together something and continue producing content
without any down time. If needed, you can also buy time by using a standard
template while they get their act together.
Documentation
Sphinx is also very well documented. This is a great bonus when evaluating it
and figuring how to make different features work the way you want them to.
What Does Not Cut The Mustard
One thing that kept getting pushed my way was the knowledge base offerings by support shops like Zendesk or Freshdesk. I evaluated both of these offerings, along with the previous Tender knowledge base used by RhodeCode.
These ticketing systems may be suitable for tracking customer issues, but their documentation offerings are very amateur. Basic word processing that sometimes supports Markdown does not scale, or even allow a writer to create a comprehensive, interconnected, congruent knowledge base. I view those as selling add-ons to pitch at people who don’t know what they are looking for
when it comes to building a knowledge base, and I have yet to see a good one!
Tools Compared in This Analysis
- DITA – I’ve used it for the last 5 years.
- FrameMaker 7.2 – I used it for 3 years, though I know that latest version 12 probably looks and feels a lot different from the FrameMaker I used.
- Sphinx – I’ve been using it for 8 months.
- The Zendesk, Freshdesk, Tender blogger apps.
- Notable absentee – MadCap Flare. I just didn’t have time.