09-16, 16:30–17:00 (Europe/London), Assembly Room
Dogs wag their tails. When the opposite happens, it represents a disturbing, problematic reversal of the proper order. But not in software and its documentation! I believe the tail of documentation can and should wag the dog of software, and I'll show just how powerful this tail can be.
The tail of the dog expresses its disposition and reflects its health, and we expect it to be a reliable outward sign of what's going on inside the dog. We expect the same kind of relationship between software and documentation: that documentation should reliably tell us about the software, providing clear and up-to-date insights into it.
I think that this is a naïve view of both dogs and software.
I will discuss, with examples, why it's a problematic idea for documentation. It's not actually true, and failing to recognise this is one reason why documentation is often so bad. Recognising the true nature of the relationship on the other hand puts documentation authors in a much more powerful position than they are usually understood to have - and that's something they can use to their advantage.
In other words, the tail is already wagging the dog, and that's the way it should be.
This talk is about documentation, but it's also an exploration and critique of some commonly-held ideas about the relationship between supposedly active and creative activities - of which making software is one example - and those seen as more passive and interpretive ones - like documentation.
Along the way, this talk will discuss topics including: the relationship between seeing and looking, riding on motorbikes, visiting museums, and why we should reconsider now-discredited pre-Newtonian theories of vision.
We'll get from dogs and their tales to an approach to documentation that improves both documentation and software, and gives us a tool for reassessing other patterns of work and life too.
I'm a Director of Engineering at Canonical, where I am working to transform documentation practice across 40-plus engineering teams. I love documentation, Python and PyCons.
I am the author of the Diátaxis documentation framework, a core developer of the Django Project since 2013 and I served as Vice President of the Django Software Foundation for several years.
I've been involved in the African Python movement for several years. I have attended multiple PyCons in African countries, and I was part of the organising team that held the first PyCon Africa in Ghana in 2019.