Ekene Kenny Eze on how to write documentation that doesn’t suck

As a part of his job as a seasoned Dev Rel expert and mentor, Ekene Eze did many documentation writing or overhauling projects. That’s why he says he felt inspired after listening to Tejas Kumar at Infobip’s Shift 2022 conference presenting on how to write documentation for humans. Ekene, who goes by Kenny, came up with his talk on how to write documentation that does not suck.

Kenny started his presentation by reverse engineering his topic and listed the characteristics of documentation that suck. The docs that suck are:

• Slow
• Too complex and difficult to understand
• Out of date
• Inaccurate
• Incomplete
• Inaccessible
• Lack of examples and use cases
• Lack of user feedback and community engagement

If you take those characteristics of lousy documentation and try to do the opposite, you get the recipe for documentation that does not suck:

Fast

Nobody likes waiting a few seconds after clicking the Docs button in the menu for the documentation page to load.

Tooling and architecture are the first things to consider when making your Docs site fast. Kenny is a big fan of using Jamstack to build your Docs sites. The second piece of the puzzle is content. Make sure you evaluate all the media assets like videos, images, or fonts and their sizes, as they are one of the main reasons for slowing down a website.

Clear and concise

Avoid lengthy, long, and complex sentences and big words. Say what your product or technology does in clear and concise sentences. People who write documentation are smart and know everything about what they’re writing about but should presume their reader knows only a little.

Documentation is usually written for tech people, but it’s still a good rule of thumb to use less technical jargon, as not everyone has to be as at home with it as you.

The idea is to write simple sentences readers can understand without doing more research and googling.

Evergreen

Have you ever copied and pasted a code example from documentation only to find out it doesn’t work? No one likes that, outdated docs are not helpful, and that’s their primary job! Keeping documentation up-to-date is something Kenny himself has struggled with in the past, so he shared a useful tip on how to solve the problem.

The challenge is often that the pace of product development is much faster than that of creating documentation. The solution is to include the process of writing documentation in the product development lifecycle. Kenny suggests doing it simultaneously while the feature is being developed (which he jokingly calls documentation-driven development).

That way, the documentation creation moves in parallel through the usual stages of development as the feature is being developed. The feature development then influences the documentation and, sometimes, vice versa!

Complete and accurate

In the same way as in the previous example, sometimes you get a code example from the documentation, copy and paste it into your project, only to realize it’s not working because the info provided is not complete and accurate. Maybe you need an API key or some kind of access token for it to work, but it’s not said anywhere in the docs.

If the docs include a code snippet, they should provide all the information needed for it to work. Incomplete documentation leaves your audience halfway to success.

Again, the idea is to provide all the information required to finish a process in one place.

Feedback and collaboration

Feedback is an integral part of documentation because you want your audience to be able to tell you if they’re struggling with a particular piece of docs or comment on the process if the docs were helpful. And a lot of docs don’t allow you to do that to share your feedback – you have to go on the company’s Slack or Discord channel to comment on something or open a ticket or a GitHub Issue if you’re struggling (which is fine if it can be done directly from the docs).

A simple thing of asking people at the end of every docs page if they found it helpful or not and thumbs-up or thumbs-down can go a long way not only in terms of giving people the way to interact with your docs but in terms of you detecting the blind spots and not so clear and helpful pages in your docs.

Regarding collaboration, a simple solution is to allow your readers to edit pages. It does not have to happen live, but when edits are reviewed and approved, it’s a great feeling for the user.

Using AI

Using AI in documentation is the new kid in town, and everyone seems to be doing it. Supabase was one of the first to introduce an AI agent trained on their docs, which meant visitors could ask the AI agent what they wanted to know and get answers. Netlify – where Kenny used to work – did the same thing by introducing a question prompt when you first open their docs – very useful because Netlify’s documentation is massive. It shortens the time needed to navigate it and improves user experience.