“Ink is better than the best memory.” –Chinese Proverb
Documenting your software can be incredibly taxing. How much documentation is enough? How should it be organized? Where do you put it? The only thing worse than no docs is an overflow of the stuff. Users need to know how to interact with your code without getting overwhelmed or confused.
Like all companies, Stormpath faced some early challenges developing our docs, but they continue to be a powerful tool for our business and we invest in them heavily. Developers evaluating Stormpath as a user management service spend 5-6 minutes reading documentation before signing up to check out our free tier. The docs are not only an important guide for users building against our system, they build trust with potential users.
Our goal was to create well-written and comprehensive docs that were also easy for users to understand, navigate and implement. Stormpath’s road to great docs is still ongoing, but here are six tips we have picked up to help you write the Best. Docs. Ever.
Ideal documentation length is widely debated. Different people like different levels of complexity or depth, based on what they are trying to accomplish. For some developers, the more the merrier, while others prefer condensed docs that get straight to critical interactions. When writing docs at Stormpath, we found that happiness is a barbell distribution: short quick starts and comprehensive product guides.
Our quick start guides for Java, PHP, Ruby and Python, are short, actionable two-pagers that guide users through key steps. When writing less, make sure what you produce is concrete: quick start guides should give the developers a taste of the full docs but focus on getting them the info they need to get their hands dirty.
The product guides represent a more thorough and detailed user guide, providing detailed and fully comprehensive docs, reaching over 50,000 words in length. Its long enough to give you a nose bleed, but surprisingly, our core API product guide is one of the most popular docs on our system because it is very easy to navigate and supplies the developer with all information necessary.
It sounds self-evident, but docs are often not built into release schedules. A feature is not really release-ready until its been documented for your users. Make sure to devote some resources in every sprint to get your docs ready prior to release. Users will bounce off your signup if they can’t find a key/new/favorite feature in the documentation.
It’s also really helpful – if somewhat aspirational – to have the docs done early. If your support team knows how a feature works before its released, they have a better chance of making users happy from day one. Its also helpful for the marketing team of a technical product – its hard to build trust with developers if your marketing materials don’t describe the feature in specific detail. Docs make that a lot easier.
Your users rely on updated docs, so it’s important to identify someone to own long-term maintenance. Bugs will be reported frequently. Docs are always changing, and someone needs to manage that chaos.
A key challenge in documentation is determining what goes where and how best to present it. You should be able to direct users to specific areas of your docs in a matter of seconds.
Get your customers to their desired destination by giving them the exact instructions they need to solve their current problem. Twitter’s docs are nicely laid out and incredibly easy to navigate with labels, images, and bullet points. Very user-friendly.
Early on, Stormpath held all information within one large file with links for easy navigation. This was way too overwhelming for our users. So, we split the content into a console guide, an API guide, and several independent SDK-focused guides. These independent guides contained all information relevant to the particular platform and became the product guides. Our new docs introduced easier navigation, and we saw time on page go down, but conversion go up!
Similar to a user guide or manual, your product guide acquaints users with the details of your particular system. It includes detailed steps and information about your specific product.
The Stormpath product guide includes a brief overview of our company and API, then dives into the details of our endpoints and calls. Because it’s a lengthier document, organization is critical. (We recommend side bar navigation!) Pictures or screen shots can also help your users visualize and navigate more quickly.
At Stormpath, we put all general administrative info at the beginning of every document, so it seems repetitive across guides for each programming language SDK. However, we find our users only typically read one guide – the language they are programming in – plus the general REST API guide. The repetition was harder on us than on our users.
As a technical writer, even if that role is a field promotion, your objective is to make your product feel as easy and intuitive as possible. Your docs connect the dots for your users and potential customers.
At Stormpath, in addition to product guides, we created a webpage of Stormpath-specific errors and another page with short “how to” content with steps for performing particular functions. Users spend about 9 minutes on our specific-errors page, allowing them to quickly solve common errors instead of searching.
Check out docs from Parse, Twilio, and Evernote for great webpage layout ideas. Each has a slightly different twist on how they present their docs. We love how Parse provides an all-in-one view, where the left-side links updated as the right pane was scrolled.
Documentation reflects your code, so it’s not a logical leap that it should be managed the same way. At Stormpath, all our docs are stored and managed in GitHub. Git allows our team to work on different sections simultaneously – as they work on features. Building a new feature? Branch your code and branch your docs. They become part of a feature, not an afterthought.
Merging is easier and more collaborative, it mirrors our development process and so is more efficient, and our team is able to release major and minor changes to docs quickly.
We also take it one step further, make the repo public. Let your community fork and patch in the same way you let them tinker with your code. Who knows, some people may help you fix errors or rephrase a complex concept.