23 March 2015

Enhancing HubPress Documentation

It’s The Docs Guy here with some thoughts about the current HubPress Documentation and how it’s delivery and presentation can be improved.

Through amazing community support, HubPress has grown considerably in popularity and features. Since starting as The Docs Guy shortly after HubPress was released, it has both surprised and delighted me just how willing community members are to contribute their time and energy translating the README.adoc. At the time of writing this post, HubPress is available in English, Simplified Chinese, Japanese, and Spanish thanks to the power of the HubPress User Community.

The Challenge

As the README has grown with HubPress, I’ve noticed that some content (embedded videos in particular) in the README just can not be displayed nicely. This is due to some limitations in the way GitHub presents Asciidoc rendered content. To be honest, README files are really only designed to contain the most basic of instructions, which can help a new user become familiar with the resources available to them in a project. To fix this problem, HubPress needs to present the documentation in a format that is better suited to more traditional user documentation, and leave the README as a launch pad for new users.

Jekyll Asciidoc Quickstart (JAQ)

I’ve been experimenting with JAQ, which is a continuous docs build system John Ericksen and members of the Asciidoctor Project created. This forkable repository was originally created to be a quick way to set up an Asciidoc Blog without all the complexity of Jekyll. Of course, when the Asciidoctor team saw just how amazing HubPress was, we needed a way to repurpose the project. I approached John because I was looking for a way to easily host Asciidoc User Guides on GitHub, without having to use a PC (I am always on an Android tablet, but only use a PC for work). John made some changes to JAQ which allowed the project to be used as a continuous build system for Documentation. To show you that it works, here is the Asciidoc guide I created voluntarily for FarSight Studios The Pinball Arcade on Android.

JAQ for HubPress Docs

As you can see, the presentation you get with JAQ looks professional and is mobile-friendly. Furthermore, as a docs contributor you don’t need to install anything to update a user guide except for a web browser. This is because JAQ uses Travis CI to build the book every time a commit is detected on /master.

Proposed Plan

I originally captured my ideas in HubPress Issue 153 but didn’t see a huge response to the issue. Based on this response, I was just going to assume that "silence is agreement" and make the changes, but that still didn’t seem right to me. Even though nobody responded initially, it would have been disrespectful of me to drop this change on the community and just have them adapt: that is poor change management, and not in the interests of Open Source collaboration.

Therefore, here is the proposed plan for discussion:

Provision a JAQ Repo.
Import the README.
Make relevant Ascidoc book structural changes:
- Chunk the chapters into separate files
- Include chapters in the root book file as "includes"
Set up Travis.
Initiate the first build.

JAQ 2.0

The way JAQ is set up now, I would need to create a separate repository for each language and manually curate a landing page linking to the generated HTML for each book in each repository. I really don’t like this structure. What I want to achieve for HubPress is to take JAQ from a static docs hub for one book to a static docs site for multiple books:

Enable JAQ to support multiple docs folders as books:
- Each book root folder has a folder node for:
  - en-US,
  - other languages as they are added.
Make the build script recurse down a source folder tree finding all the books and publishing each one when a commit is detected.
Regenerate the docs landing page.
Generate a changelog for the book from the GitHub PRs (nice to have).

Not only will this allow HubPress to have a dynamic docs site, it will allow small to medium enterprises to quickly create a docs site for their customers using the flexibility of Asciidoc and Asciidoctor.

Feedback

Now you’ve read my ideas, go ahead and give your feedback in HubPress Issue 153. This is a community effort, and no idea will be dismissed as long as it is constructive.