Quality documentation matters. But in software development, documentation is often seen as an afterthought or, worse, a hurdle in the way of progress. Although maintaining documentation may not be the most appealing activity, it can pay big dividends in the long run. Great docs enable self-service technology platforms, reduce manual support requirements, and retain consistency and discoverability across a burgeoning portfolio of microservices.

But there are specific standards developers have come to expect from their documentation, especially from Software-as-a-Service (SaaS) and API-first companies. Our LiveCast on API Documentation Best Practices explored some of these areas. Below, we’ll share some best practices for creating stellar documentation and consider how one API-first company is optimizing its developer workflows by fine-tuning the documentation experience.

Why Quality API Documentation Matters

First off, why does great API documentation matter? For one, intuitive reference documentation improves the developer experience (DX). Documentation is often the first impression a developer has with an API. And it’s important to have thorough, up-to-date reference documentation throughout the software lifecycle to maintain integrations. Good documentation practices also help avoid tribal knowledge and sustain knowledge retention when engineers switch to other companies.

Documentation is the mirror into the company, says Pam Goodrich, Technical Writing Manager, Stoplight.

Documentation and sample code are the most important features that companies should offer to support developers, found the Developer Nation Q3 2021 survey from SlashData. Excellent documentation is also integral to enabling a self-service technology platform. Engineers are unlikely to buy a software product without first looking at its documentation, and transparent reference documentation really helps define boundaries and inform the product overall. “You can’t really do self-service support if you don’t have good documentation,” said Goodrich. “It’s a mirror into a company.”

Imagine a PDF that is printed and mailed to your client developers. That would be an example of a pretty lousy developer experience. Unfortunately, in some scenarios, this is not too far from reality. Untransparent and unnavigable documentation can introduce friction and slow down progress. And for API products, it could even hurt sales and prevent a bottom-up developer-first tooling acquisition model from emerging.

5 Questions to Ask To Improve Your API Documentation

So, how can we make our docs as streamlined as possible? Goodrich shared a handful of excellent questions to consider as you work to improve your documentation. Finding the answers to each should greatly help improve the quality of your documentation and developer experience in general.

1. Who is the audience? SaaS providers often have both product documentation and API documentation. And satisfying the needs of both begins with determining your audience. This will determine if your documentation is for internal consumers or can be ungated and public.
2. Is your documentation discoverable? We can’t understate the benefit of transparency for documentation. Ensuring these docs are discoverable, navigable, and searchable is vital for developer experience. This can be accomplished with a nice landing page, table of contents, and intuitively designed docs, said Goodrich. On that note, API documentation often adopts a three-columned approach, with paths navigation on the left, method descriptions in the center, and sample code on the right panel.
3. Is your style consistent? Ensuring developer-facing content has a consistent tone and style is often overlooked, says Goodrich. Following a style guide, such as the Microsoft Techincal Style Guide, she says, could be used to enforce governance, create consistency, and improve your products overall. She also recommends Vale for checking docs, and Spectral for linting your API definition.
4. Is your content up to date? Content like screenshots or walkthroughs can quickly become stale and outdated. Goodrich recommends keeping screenshots to a minimum and reviewing tutorials to update them periodically. Outdated information could cause confusion and dissuade users from picking up an API.
5. Is your content bloated? Streamlining your content can aid findability and usability, says Goodrich. As such, it’s a good practice to avoid duplication whenever possible. “Reuse is important, but don’t abuse reuse,” she said.

Docs Are More Than Docs

If developers are your primary customer, you must ensure they’re well taken care of, says Arnwine. He recommends starting from a reactive stance to understand the state of your documentation. This involves gathering as much feedback from developer advocates and consumers as possible to resolve common bottlenecks. Doing so should identify user experience gaps, like inconsistent terminologies, navigation troubles, and other hurdles.

“Docs are a garden you must continually tend to,” said Ash Arnwine, Director of Developer Relations, Nylas.

After you’ve resolved these issues, you can begin to take more of a proactive approach. For Nylas, this has involved incorporating documentation within the product lifecycle process and establishing more repeatable workflows. Once you’re in this proactive state, you can set a roadmap to level up with cooler engagement features too. For example, Nylas is working with Fig to enable auto-complete. They’re also rolling out a step-by-step dynamic walkthrough to tailor DX to the specific use case, stack, and language the consumer is using. In essence, documentation can encapsulate more than just words on a webpage. “Docs are more than docs,” he said.

Yet, overseeing documentation can be a bigger task than you may think. “Treating docs as a part-time job won’t get you far in the long run,” said Arnwine. He shared how Nylas decided to hire a dedicated team for its documentation strategy. The ideal documentarian, describes Arnwine, is process-minded and can see and execute a strategy. Although these documentarians don’t necessarily need to code, they should be technically minded and understand the tooling for managing document infrastructure.

As a result of their documentation optimizations, Arnwine shares that the team at Nylas has noticed improved SEO results and received very positive customer reviews. The investment into self-service tools is decreasing manual support efforts and has also led to higher-quality sales leads, which has helped to spur new business.

Improving DX With Documentation Best Practices

Sometimes, it can be tricky to justify enhancing the API documentation experience. Amid economic uncertainty, developer relations and documentation teams might even be de-resourced. As such, upper-level management may need to be convinced of the benefits of proper documentation management. Thankfully, the case is much more apparent for software companies with developers as the primary consumer. (Some of which have even welcomed the chief developer experience officer as an executive role).

Furthermore, advanced AI like ChatGPT and GPT-4 are set to change much concerning the software development workflow. And new automations within IDEs could negate the need to even check the documentation for some use cases. But although these are interesting developer experience perks, our speakers believe the complete reference still must persist as a core foundation. Otherwise, it’s hard to trust what you’re getting into.

As more companies become software companies, more will attempt to open up (and monetize) their data and infrastructure. As such, high-quality developer experience is becoming a valuable technique to stand out in the market. Looking to the future, the need to improve developer experience through optimized documentation will likely become a more widespread concern.