Cross-posted from: http://harlankellaway.com/2014/03/17/online-documentation-platforms/ (March 17, 2014)
Documentation for technical projects — especially ones you envision having non-technical end users — is essential. This statement comes from various experiences, both as a user and a developer who has both produced documentation for such users and has taken over poorly-documented projects from other developers. Having good documentation cuts down on the endless issues that come with figuring out how to use a technical product, whether from the frontend or the backend.
The reason documentation is on my mind is that one of the current projects I’m doing development for, DH Box, is one targeted towards end users of the variety described above. Not only that, but one of the systems integral to the project is a notoriously opaque one: Amazon Web Services. Moreover, it’s a mission of mine in my personal work to explore how tech can be made more accessible to those who don’t deem themselves technically savvy (I consider the technical/non-technical social binary and contributing factors to be problematic — but I’ll save that exploration for a different post!).
This week, I explored some tools that could help maintain the online documentation for our DH Box project, with a few preferences in mind: documentation that is easily updatable, documentation that is browsable and searchable, documentation that is configurable (e.g. in how it looks).
Fellow DH Box dev (and founder), Stephen Zweibel, suggested the following platforms given our project uses GitHub for code hosting and our site is pure HTML generated by static site generator Jekyll.
HasDocs
The first platform I took a look at was HasDocs. The reason I went for this first is because one of its features is integration with Jekyll-based sites — which ours is. What HasDocs does (similar to ReadTheDocs, described below) is generate documentation on their servers that can be triggered to regenerate every time commits are made to GitHub for the project for which the documentation is associated.
What ultimately took me away from HasDocs is it didn’t seem to work (at this time) with GitHub repositories owned by Organizations (as opposed to individual users).
HasDocs has a few features I like: it has a search engine built in, a clear layout with Table of Contents, the ability to customize the look, etc.
One small difference to note about the workflow of HasDocs versus ReadTheDocs is, HasDocs has you Import all repositories associated with an account for it to generate documentation for — then you can delete the HasDocs documentation for the repositories you don’t wish to maintain documentation for. ReadTheDocs, on the other hand, has you create ReadTheDocs documentation individually for every repository. This might come into consideration if you had many many repositories that you wanted to all generate documentation for.
Example of HasDocs documentation: http://yoonchee.hasdocs.com/wand/
Read the Docs
Read the Docs is similar to HasDocs — it generates documentation on their servers that can be triggered to regenerate every time commits are made to GitHub for the project for which the documentation is associated.
The reason I didn’t go for Read the Docs initially is that it was not build to generate documentation given files set up for Jekyll (note: this doesn’t mean it’s unusable with Jekyll sites). Read the Docs uses Sphinx markup to generate documentation. This means that our maintainers may have to learn a different markup to help maintain if this is more efficient than writing pure HTML.
ReadTheDocs also has the features I liked about HasDocs: search engine built in, clear layout with Table of Contents, and ability to customize the look, etc.
Example of ReadDocs documentation: http://docs.writethedocs.org/
Metalsmith.io
Lastly, Metalsmith.io, a fairly new tool, came up. The reason Metalsmith.io was not ultimately chosen is because it’s just too new at this point in time and, as a cautious developer, I try not to adopt tools that haven’t been used for quite a while. Additionally, Metalsmith.io is not a dedicated documentation platform, but rather a static site generator (like Jekyll) that can facilitate generation of documentation.
There are other platforms for helping maintain documentation, and this isn’t a direct endorsement of any tools listed here (I’ve only just started using ReadTheDocs!) — rather it’s meant to be a look at considerations I made when choosing a platform.
What I’d like to emphasize is that documentation is important, maintaining documentation online has certain benefits (ease of access, maintainability by various contributors, search capability, etc.), and finding how to make maintaining it easier on maintainers can really help.
