Better documentation—better platform Developer Experience

 A core value in Agile work is “Working software over comprehensive documentation”. Too many developers take this too far, though. 

They forget that it’s crucial to provide documentation on how to work with their software. (Involuntarily) they sacrifice Developer Experience (DevX) for agility. But it doesn’t have to be that way: you should aim for both. 

In this post, I will show you why good, clear, and concise documentation should be a top priority in platform engineering. And even more importantly, you will learn how to ensure you have just the right (and the right amount of) documentation to keep developers happy, without overdoing it. 

Documentation is a BIG topic. So, to narrow it down, I will zoom in on these headlines:

• Why documentation is important — What's in it for you as a platform engineer and the people relying on your platform?

• Where you should start — What kind of documentation should you start with?

• How to get feedback on your documentation …and how to make this actionable

Let’s get started. 🚀

Why documentation is so important

If you’re on a platform team, part of your teams’ API includes:

A contract with developers 

This includes everything developers need to interact with your platform programmatically. Think of APIs, CLIs, Libraries, etc., for the software you own. The contract also covers the Service-Level Agreement (SLA) — your promise to developers on the reliability and availability of your services.

Documentation 

This is especially developer-facing documentation for the software you own. Content like READMEs, getting-started and how-to guides, and conceptual and troubleshooting documentation.

Your ability to provide well-structured, clear, and concise documentation significantly raises DevX for those building their software on top of your platform. 

You have probably experienced poor or lacking documentation. It is annoying, and you end up wasting a lot of time trying to guess how to use others’ software.

So, without good documentation, DevX is degraded and the value of your platform diminishes. As Kelsey Hightower puts it:

“If developers are the superheroes of the software industry, then the lack of documentation is our kryptonite.”

Where you should start

Before going into the specific documentation content types, here’s a common caveat. 

An anti-pattern that hits us all, especially when writing to other developers and engineers.

It is important to be aware of the “curse of knowledge”. We inadvertently assume others understand our platform and the underlying systems just as much as we do. 

But they don’t. And they shouldn’t. 

That’s the whole point of a platform's goal of reducing complexity through sets of well-defined abstractions. So, you’re actually violating that rule and leaking abstractions unnecessarily through your documentation.

Instead, you need to have empathy for the developers. Identify their goals with your platform and help them achieve these goals, given their context.

But how do you identify developers' goals with your platform?

Start with Who

You may have a lot of assumptions about your users’ goals. But until you do some research, the assumptions have not yet been tested upfront.

If not, you risk building things that are not: 

• viable (not meeting the needs of the developers)
• feasible (not delivering the value with quality in mind)
• usable (the value can’t easily be experienced by developers)

Therefore, it is important to understand the developers and their needs and pains.

This is the essence of treating your platform as a product. You need to figure out how to do “the right things”.

Let’s assume you have this well-covered and your software is both viable and feasible. To greatly improve usability, documentation comes in. It is the same principles and condensed knowledge that you should apply to your documentation. That means understanding your users’ goals for every type of documentation and making it easy and cheap to consume.

Create a documentation plan

Do you know if your documentation feels like a maze to your users? Is it hard for them to reach whatever goal they’re trying to achieve?

Photo by Victor on Unsplash

The aim of a documentation plan is to anticipate what kind of documentation your developers' need, given the challenges they’re currently facing.

If you’re in doubt about the current state of your documentation, here are some tell-tale signs that your documentation lacks something or is simply not good enough:

• Developers have a hard time getting started using your platform and its services. They often need your guidance. (getting-started)
• You often feel you need to repeatedly explain how <x> works. (conceptual)
• Developers explain that they tried to follow your documentation, but failed at some step because they didn’t have the right version of <x> installed. (how-tos)
• When developers fail to achieve their goals with your services, they call you instead of reading the documentation (troubleshooting)
• You keep directing the same people to the same documentation, but somehow they forget about it. (documentation plan/structure)

Once you have a better view on the state, it’s a good idea to create a content outline.

Here’s an example:

Get some feedback on this outline from your users and once you’re ready, start writing or editing according to your outline.

“Getting started” is a good entry point

In the following I assume that you already have a central place for your platform documentation. It might be, for example, a:

• Confluence space
• static website 
• GitHub repository 

The first self-service impression of your platform is most likely the documentation landing page and the sense of the overall structure here, according to your documentation plan.

Next, they will probably look for the “Getting Started” page and go here. Make this page count, as it sets the overall expectations of the rest of your documentation and the platform as a whole.

The “Getting Started” guide should provide a clear overview of what the platform is all about, what its core features do, and how to get started using it. This is great for developers who are just starting out and need a quick and easy introduction to the platform.

Remember to be concise and avoid going into too much detail on how the platform solves specific problems. Save the “hows” for the deep-dive conceptual documentation.

From your research, you should have a good understanding of developers' needs. Keep this in mind and address the most important questions they have when they onboard your platform.

Furthermore, a getting started guide can help to alleviate some of the anxiety that comes with learning a new platform. It can be overwhelming for new developers to jump into a complex system without any guidance, but a well-written getting started guide can make this a much less intimidating experience.

Therefore, a “Getting Started” is a great place to start. It provides an overview of the platform, sets expectations, and helps alleviate anxiety.

How to receive feedback on your documentation

Once your documentation is out there “in production”, it’s time to test whether it solves the problems you aim for. Start by listening to your developers.

Listen to your developers

Developers reading your documentation expect that they can give you feedback on this. It’s everything ranging from spelling errors, to something that is plain wrong or a concept that is hard for them to grasp.

So listen, understand and thank the person for taking the time to give you this gift.

This may not be the easiest part. I know for myself that I can feel a little defensive on something I have spent a lot of time on—maybe even start to argue or explain why it is that way—and that is typically when we miss the opportunity to understand their perspective.

Instead, ask some follow-up questions to make sure you have covered it all, and then allow yourself some time to reflect and find out what to do with the feedback.

When you take feedback seriously, say thanks and show that you're open to change things based on what you learn. You actually build trust. I’ll bet this will strengthen the feedback loop. 

Create feedback channels

If it’s too difficult for people to provide feedback, they may be less inclined to do so.

Like I said, being open to feedback removes a lot of this friction. But you also need to create the channels that allow for their feedback to flow to you. Here are some examples:

Dedicated Slack channel

For example #platform-documentation-feedback. This has the added benefit that others can easily chip in.

Built-in features in the wiki 

For example, page/line comments and the “Was this page helpful?” yes/no simple surveys.

But it also covers editing or suggesting changes directly, or through something like Pull Requests.

Surveys

Keep in mind that good surveys require some skills to both ask the right questions and process the results so they can provide you with actionable insights. There’s nothing more annoying than getting hit with bad surveys—and you risk the opposite of what you're actually trying to achieve: improve DevX.

So, surveys require a bit of research and planning. Below is my candidate for questions to a “Getting Started” guide.

With our “Getting started” guide:

• Is it clear what this platform is and what it is not?

• Is it clear what we set you up to achieve?

• Is it clear what problem it solves for you?

• If so, did it actually solve said problem?

• If not, is it clear what to do then?

• Do you think it takes your context into consideration in terms of:
  
  • Level of expertise
  • Role
  • Environment (OS, tools, etc)

• How can we improve?

• Any other comments or things you want us to know?

Support issues

You probably already have set up a template for developers to submit bugs they discover on your platform. If so, just use the same process for documentation, and handle it as such.

Analytics

Here you’re also taking readers' behavior into account. Seeking answers to questions like:

What pages do they mostly visit? How long do they stay there? Do they even complete the step-by-step guide?

Let’s wrap up

Start with understanding your developers and their needs, this requires some research.

Challenge the “curse of knowledge” bias by understanding their goals and context. Ensure that your platform (including the documentation) is viable, feasible, and usable.

Create a documentation plan to give structure and put the right content where it needs to be.

Actively seek feedback by setting up the right channel. Be open to receive it and change things from what you learn.

Lastly, remember to treat your platform's documentation as a first class citizen. Put as much quality and effort here as you do with your software.

If you want to dive deeper into the art of writing technical documentation for developers, I can highly recommend the book this blog post draws inspiration from, here:“Docs for Developers - An Engineer’s Field Guide to Technical Writing” by Jared Bhatti, Zach Corleissen, Jen Lambourne, David Nuñez, Heidi Waterhouse