I'm a big fan of good documentation. It's hard to do, and doubly so with poor tools.
At work we've been using API Blueprint for documenting our systems, and while it's been serving us well, the tooling leaves me wanting more.
Some of the problems I have:
- Responsiveness: I don't mind a slow compilation step, but a lot of the tools struggle with large files, leaving a slow page render and no free RAM on my system
- Automation: I want to build my API docs from a GitHub repo and push them wherever. There are tools like Aglio that can do this, but the output is visually very dated and incredibly slow
- Readability: Apiary is beautiful but doesn't support automation super well, since it primarily wants to be an online editor. None of the third party tools come close in terms of features or general experience.
With that in mind, this weekend I figured I'd try my hand at generating some docs using Ractive (the virtual dom-like mustache templater) and Bootstrap 4.
Proofer (a frontend to Drafter)
The result of my work is a little project called Proofer (a frontend to Drafter) with the aim of letting developers quickly create and manage templates to render documentation.
It has two parts
- A backend renderer which renders an API Blueprint file into a JSON equivalent
- A frontend render which takes the JSON and outputs HTML
It uses the emscripten-compiled Drafter.js library rather than the full-fat C build, because npm packages with a compile step jangle all my pet peeves.
This also means that in the future we can implement client-side authoring and intelligent differential updates using Ractive (which as an aside is something that I'd like to see Apiary do too).
Performance
So how does this implementation stack up?
It's a client-side rendered single page app which definitely satisfies the responsiveness criteria. Only the stuff you're interested in gets loaded into the DOM, and the content is only rendered as you navigate between categories. This is lightning fast on an initial page load.
You can see that the render of our large API Blueprint akes less than a second. There's a fair bit of JS parsing waste that could possibly be fixed with an async load, but this is not too bad considering our existing render takes a good twelve seconds thrashing around with jQuery UI before the page is loaded.
I always noticed, but never realised just how slow our existing docs had become.
(An amusing aside, the Apiary editor had crazy memory leaks and would chewing up gigabytes of RAM editing our documentation in Chrome before we moved authoring to GitHub.)
Other niceties
In terms of readability, this is wholly subjective. I don't think the layout is super amazing, but It's using Bootstrap 4 for styling which I think is a good base to work on, and it's something I'll continue to develop.
One of the killer features though, is the integration of Ace Editor for payload rendering. You can click “view in editor” on any JSON glorb to open it up in Ace where you can quickly search, edit, do code folding etc. For APIs returning large payloads, this is priceless because standard JSON rendered into the page is really hard to navigate.
Finally, in terms of automation this isn't quite there yet. While it has the command line app for the build step, I'd like to split out the components so others can easily build their own documentation. At the moment this is still tightly coupled, though won't be difficult to break up.
Conclusion
Interestingly, the easiest part about this project was the parsing since the heavy lifting had already been done by the good folks at Apiary.
The toughest part is styling the output to be both visually pleasing and useful, something that I'm planning to continue working on.
Ultimately the most important part is having the documentation in the first place. I've joked with my colleagues about quitting my day job to follow my passion of being a technical writer… but for now I'll stick to doing both.
You can fork the project on GitHub or see some preview output of a fictional API.