Discoverability

For a while we had a column on our sprint board called “Documentation”. It was a catch-all column to help us remember that things weren’t “done” until they were shared. They say that if you build a better mousetrap the world will beat a path to your door. That may be true, but only if the world knows you built it. Yes, iIt’s possible for word of something to leak out and for usage to grow, but that’s not the normal case. Better is to tell people what you’ve built and why it’s better for them. That’s where documentation comes in.

We wrote the infra tool to help us manage our infrastructure and help our customers use it. One of the first things we added was the auth module. Because we wanted a good way to update all of the different contexts and tokens once and not have to worry about it. We didn’t tell anyone at first. Just used it ourselves and enjoyed it. Some people noticed and started using it. Then we started getting questions about how to use it. That didn’t make sense since it was fully documented, wasn’t it?

Well, it was, in that the docs, online and off, explained exactly what options were available and what every option meant. But there’s more to documentation than that.

It starts with a good description. What does this thing do, and why should a user care? What’s the benefit? Remember, people generally buy things for the benefits, not the features. In this case,

This utility allows you to add authentication profiles for external services
that can't integrate with uSSO (currently only AWS). Then, at the start
of each day, you can refresh the credentials for for each profile en masse,
only entering your password once (though potentially 2FA-ing multiple
times).

So a clear benefit.

Then there’s how to get it. With the infra tool, as long as you’re in the rNA repo, it’s just there. And it auto-updates. No need to do anything. That’s the best kind of docs.

And of course you need to have a full description of the API (or CLI in this case). All of the functions and parameters. Each with not just a what, but a why. In many ways this is the easy part. For the infra tool you can see it at any level with the --help option, like infra auth --help.

You want to have examples. Both targeted ones and general ones. For the `infra` tool it includes things like a specific example of adding a new profile (`infra auth add-aws-profile --help) as well as the more general codelab that show you how to use it day to day.

If you’re writing a library (or expecting others to contribute to your tool) you also want a “how we did it and why” section of your docs. For the infra tool that part lives with the code and in our internal docs, but it’s there. We’ve even got a presentation on how you can extend the tool. But we keep it separate because it would get in the way of our users knowing how and why they will benefit from it.

So next time you think you’re done with something, look at the documentation and make sure you’re really done.