Logo

mobileteashop

Dennis Poon's blog and ersatz portfolio.

Webifying Docs From a Bygone Era

Recently, we finally decided to convert our old developer documentation from its original format - a series of Microsoft Word docs - to an online format. We ultimately decided on a Jekyll + GitHub Pages setup for maximal dev-friendliness and simplicity.

The Problem

Our developer docs are maintained by our Dev team, so we had to decide internally how to tackle the problem. Initial discussions went something like this:

  1. Convert Word doc contents to appropriate text-based markup (HTML, Markdown, etc).
  2. Put contents on some public-facing web space.
  3.  ???
  4. Profit!

Developers being developers, at first it seemed that this would be mostlty a format conversion problem (maybe sort-of fun! Let’s write some scripts and regexes!). But soon after, it became clear that this problem was moreso a content management problem (booo!).

How do people update content? How do we deal with site design and layouts? How do changes go live? We broke down the problem into the following three issues:

  • Content creation - content includes API updates, code examples, step-by-steps, and informational articles. The process of creation also includes reviewing/proofing content.
  • Content presentation - Creating the HTML, CSS, templates, menus and everything else needed to make things look good (enough) for display.
  • Content publishing - Where is the documentation hosted, and how are updates propagated to the live site?

Taking into account the above, we wanted as simple a solution as possible.

The Solution

After wrangling around with different tools and approaches, we came up with the following:

  • Static site generation via Jekyll (in lieu of a CMS/publishing tool).
  • Documentation to be stored as text/markup in Git, specifically in GitHub.
  • Pages to be hosted on GitHub Pages using built-in Jekyll support.

Why This Works for Us

The solution satisfied the three main content management issues we had identified:

  • Content creation - Deveoper docs are maintained by the Dev team; using familiar tools (Git, GitHub) and no-frills markup makes this process easier. It’s easy to review and approve (or rollback!) changes.
  • Content presentation - Static site generation makes for very accessible modification by web designers. Nothing is hidden by the inner-workings of a CMS so the designer has full control over all aspects of the design and layout.
  • Content pubishing - automatic page generation via git push and GitHub Pages is devilishly simple (and free!). GitHub Pages also does not preclude us from manually publishing pages later on.

In terms of simplicity:

  • Overall tool/application footprint is small. Nothing onerous required; the only install needed on top of our existing setup is Jekyll.
  • Git and Jekyll can be easily incorporated into our automated build and release processes/scripts.
  • Since our documentation is pretty much all static, Jekyll is a good fit (particularly because of GitHub pages).
  • We already host the code for our client libraries on GitHub, so it’s a no-brainer to put more stuff there.

Some Considerations

Using a Wiki or CMS

Our first instinct was to look at a wiki-based solution. This would provide for easy editing/cross-linking of content. However, neither a wiki or CMS really provided us with enough flexibility vs. the hassle of deployment/customization/platform maintenence. Given the amount of documentation we had, a large up-front platform investment wasn’t worth it.

API-level Doc Generation

The original API-level documentation was written by hand separately from the client libraries. In our quest for improved workflow, we considered sourcing the API documentation via Javadocs (or equivalent for other languages) for the client libraries. The Javadocs are closest to the code level and easily maniuplated by devs. Plus there are plenty of tools to apply custom templates to the generated html.

In the end, we decided against this approach (at least for the time being). The main driver was that our “API-level docs” demand supplementary information; the payments space doesn’t function well without some sort of domain explanation to accompany the docs. That kind of information doesn’t sit well at a method/function level.

Conclusion

A Git + Jekyll + GitHub Pages solution for publishing developer documentation worked well for us. Developer and designer-friendly tools provide low-overhead content creation. Single-command publishing makes getting our content live effortless. An extremely light, scriptable set of tools makes for easy setup, ramp-up, and gives us the flexibility to expand if required. If you’re looking for a lightweight solution for publishing documentation, this setup is a good place to begin.