Session

If you’re building something for developers, you want it to get used. This means your potential users need to find your library, framework, or API. They need to work out whether it’s useful for them, learn how to use it, and solve problems they encounter along the way. All these things depend on your developer docs!

This talk is about important functions of your developer docs that you might not think about, some particular pitfalls of documenting things for developers, and how we can make things better.

Did you know that:

• Your docs are content marketing? Your prospective users are out there, Googling “how to [what your project does]”, and your docs are the answer.
• Your docs define your product? When a developer is evaluating your project, this is what they’re reading, not your glossy website.
• Your docs are your user interface? Developers using your API aren’t looking at your website - they’re looking at your docs, and their code.

So let’s look at some “dos and don’ts”:

• Do know what type of doc you’re writing. Tutorials are not the same thing as reference docs. I’ll walk you through a useful framework for thinking about types of documentation.
• Don’t confuse reference docs and API docs. Merely enumerating the classes, methods and functions of your API isn’t enough to describe its behaviour. I’ll explain why it’s tempting, and why it’s a bad idea!
• Do make it easy to navigate between types of documentation. Your user is on a journey, from “what should I use?” to “how do I use it?” to “what arguments does this function take?”. Make it easy for them.
• Do talk to your users. They will tell you where the weaknesses in your docs are. Even better: have a public Q&A forum, where deficiencies in your documentation get found and filled in, and the long tail takes care of itself.

I hope to convince you that your docs are your UI, your marketing and the definition of your product - and that it’s worth acting like it!