Writing Better Documentation for Developers

Meredydd Luff (~meredydd)


Description:

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.


Your docs aren't just docs:

  • They're your user interface: When a developer picks up your tool for the first time, the first thing they seriously look at is your documentation.
  • They're your marketing: Your prospective users are out there, Googling "how to [what your product does]". Your docs are literally the answer to that question.
  • They define your product: What's your library good for? What's your API's "sweet spot"? Your users don't know...so they'll consult your docs.

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.

Your docs are your UI, your marketing and the definition of your product - so act like it!


Timing projections:

  • Intro (1 minute)
  • "Your docs aren't just docs" (5 minutes)
  • "Know what type of doc you're writing" (4 minutes)
  • "API docs aren't reference docs" (6 minutes)
  • "Make it easy to navigate between types of docs" (4 minutes)
  • "Talk to your users" (4 minutes)
  • Conclusion (1 minute)

Prerequisites:

Anyone who wants to publish a package on PyPI, or get developers to use their company's API, is in the business of "selling" it: making it easy to find, pick up and use. That's the job of developer documentation, and this talk will help them do that.

Video URL:

https://youtu.be/OCzCr2Jmazo

Speaker Info:

I built and maintain a developer platform (Anvil) that gets regular compliments on its docs, and co-led the design process for our current documentation system.

I have previously given this talk at PyCon US 2021, where attendees gave it the highest rating of the conference. I have also spoken at PyBay, Python Web Conf (invited) and keynoted PyCon SK (also invited), as well as giving a few lightning talks.

I hold a PhD in usable programming systems from the University of Cambridge, and I have contributed to projects ranging from the Linux kernel to the MQA audio codec.

Speaker Links:

I am one of the original creators of the Anvil web framework: https://anvil.works

Section: Others
Type: Talks
Target Audience: Intermediate
Last Updated: