Communication Community Development Documentation Teaching
See in schedule: Thu, Jul 29, 13:45-14:15 CEST (30 min)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 are content marketing. Your prospective users are out there, Googling "how to [what your product 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.
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.
Your docs are your UI, your marketing and the definition of your product - so act like it!
Type: Talk (30 mins); Python level: Beginner; Domain level: Beginner
Meredydd thinks programming should be more accessible. From discovering that QBASIC was the best toy ever, to a PhD in building usable programming systems, he wants other programmers to be able to have the same fun he's having. These days, he's a founder at Anvil, which makes full-stack interactive web apps as simple as writing a Python program.
