Beth Aitman - A practical guide to making good documentation

Documentation is the major way that developers learn how to use a new technology(1) (with Stack Overflow a close second, obviously). And good docs make a huge difference to usability - all of us have struggled to use something because of poor documentation(2). In particular, docs for Haskell libraries have a reputation for being pretty opaque.

So we know that documentation is important. But writing it is kind of a pain. And so many developers don't really bother.

The goal of this talk is to make it much less painful for you to write documentation - and possibly even enjoyable. I'll give you a practical guide to writing effective documentation, and the conceptual background you need to understand the problem space.

We'll cover:
what to write, and how to work out what you need to write
tips for making your writing clear and easy-to-read
making docs work for your audience (aka - when it is and isn't appropriate to talk about category theory)
how to put docs together in the Haskell ecosystem, and what should go where
maintenance and testing
with plenty of examples of good and bad along the way.

(1) https://insights.stackoverflow.com/survey/2018/#developer-profile-ways-developers-learn-on-their-own, https://insights.stackoverflow.com/survey/2017#developer-profile-ways-developers-teach-themselves
(2) https://insights.stackoverflow.com/survey/2016#work-challenges-at-work