Building a Theme Optimized for Developer Documentation
Over the years I have worked on designing and implementing numerous websites to help developers learn and become successful in building products on top of a company’s platform. I have built and developed websites for TokBox, Uphold, Roblox, and most recently at RingCentral.
As with many design initiatives, the output of these projects is limited to the website itself. However at RingCentral, where employees are encouraged to share their innovations more openly, I am happy to make available to the developer community Moonstone, a mkdocs theme that incorporates much of what I have learned along the way into a solution that makes it much easier to build, deploy and maintain API documentation and a developer website.
So what were the principle design objectives for the new RingCentral Developer Guide? And how did these manifest in the product we built?
Easy to Write and Edit
All documentation should be easy to edit by those responsible for doing so. Developer documentation, however, is often unique in that the number of people who might actively contribute to documentation is quite large, e.g. an entire engineering organization, or a developer community. Furthermore, documentation may sometimes reside in external source control systems or swagger specifications for which HTML and other rich text formats present many challenges.
We wanted documentation to be readable on and off the website. In and out of source control, and in and out of YAML and JSON files. That is why we wanted a system that was designed around markdown — a way of writing simple and readable text documents that can be easily converted into markup/HTML.
Markdown, however, is not perfect out of the box. If you really care about the design and layout of your content, then you will almost certainly find that markdown’s utility quickly breaks down as you hit the limits of its simplified syntax. Either you must be satisfied with an incredibly limited design palette, or you must embed HTML into your content. Both felt like compromises I would regret making.
Mkdocs, however, is a platform written in Python and makes readily available to its users a number of Markdown extensions. Moonstone makes use of a number of these (which you will see later) which convert simple text into more complex UI elements. For example, this custom markdown syntax:
!!! warning "Some Alert Title"
More text to display in the admonition box. Produces the following:
With Moonstone, developers get the best of both worlds: pure-markdown documentation and highly styled UI elements.
Easy to Update, Easy to Collaborate
Creating and more importantly maintaining great developer documentation is a team effort. Whether you are looking to leverage the expertise of an open source community or your company’s engineering team, documentation must be as easy to edit as the source code that powers that which is being documented.
Mkdocs is a simple documentation framework that can be easily incorporated into any source code repository. Once in place, developers can easily run a copy of the website locally as well making it easy to preview changes before they are published. In addition, having your documentation live alongside your source code:
- Makes it easier for developers to update as they hack on a product.
- Makes it easier for maintainers to process pull requests as they can evaluate code and documentation changes together.
- Makes it easier for teams to share and provide feedback on changes under development.
In other words, documentation can become an integral part of the change control process rather than being relegated to an afterthought, which is too often the case and ultimately leads to poor and out of date content.
To help foster a collaborative and team-oriented approach to documentation, we created mkdocs-git-committers: a mkdocs plugin that allows one to display a list of contributors to any page in the documentation. This small amount of recognition has helped fuel community contributions to vast documentation sites like Microsoft, and it is our hope that it will have similar effects for us and others.
Beautiful and Customizable
We wanted Moonstone to be beautiful in its simplicity. Plain, but not without personality. We wanted a theme that could stand on its own, or be easily customized to take on the brand of any product or company.
We started with Bootstrap, a robust CSS framework that not only provides Moonstone with a fully-adaptive, super-clean canvas that works across all browsers and devices but also an expansive library of UI components that harmonize well with each other.
We then bundled additional styles and UI elements commonly used by developers in their documentation so that nothing was overlooked. These include:
Syntax highlighting
While code highlighting is table stakes for developer docs, we wanted to go one step further by providing optional line numbering and line highlighting, all using a pure markdown syntax.
Fenced code blocks
Stack code samples one on top of the other to create tabbed code panes. Organizing code in this way helps preserve screen real estate, and more easily relate code sample to one another. They are great for allowing readers to toggle between code samples written in multiple languages, or request/response pairs common to APIs.
Admonitions
Often you need to bring the readers attention to an important detail. Call-outs alert readers to warnings, best practices, or a simple “FYI” to signal where they can go for further reading on a subject.
You can also keep documentation focused and clear, by hiding documentation behind expandable blocks.
In keeping with our first design goal of making documentation easy to write and edit, we implemented all of the above using markdown extensions so that your docs are never unnecessarily muddled with HTML. We even created the mkdocs-bootstrap-tables plugin to seamlessly convert the bare-bones tables created by markdown, into bootstrap compatible tables so that every aspect of your documentation harmonizes perfectly across your site transparently and automatically.
Why Moonstone?
For those of us building developer oriented products, like APIs or SDKs, it would be a mistake to think that our products lack a user interface. Our documentation is often the first thing our users encounter, even before they have even actually used our product much less downloaded or installed it. Afterward, our documentation becomes the resource our users consult the most — and one of the largest contributors to our products’ success.
We created Moonstone because we believe that documentation IS our user interface, and we should take as much pride in our documentation as we do in the products we craft using the SDKs, APIs, and developer tools used to build them.
Byrne Reese is a Platform Product Manager at RingCentral who advocates for Developer Experience, education, and tools.
