2024-09-22 –, Tutorial Track B
Of the multiple obstacles that get in the way between good intentions and successful software documentation, the most difficult to overcome is a lack of confidence. It's very hard to make progress in any endeavour, if you're assailed by doubts that you are doing the right thing or doing it the right way.
This workshop introduces a repeatable, reusable approach to the documentation confidence gap. It will help get work started and then helps keep it moving. We'll apply it - from the very first few minutes of the workshop - to participants' real-world documentation challenges.
The methods, tools and principles that this workshop introduces have been developed and refined over years, and put into practice at scale. They are systematic and proven.
I have run this workshop multiple times, with consistently effective results for participants and their documentation projects.
The gap of confidence thwarts the documentation ambitions of organisations, teams and individuals.
It might seem odd to identify a gap of confidence (rather than of understanding, knowledge, capacity or desire) as the most significant obstacle to success in documentation. However, time and again it's confidence that proves to be key that unlocks progress.
People who want to get documentation work done, even those who have a clear idea of where they want to get to with it, are often not sure where to start, or what to do next, or they suffer from doubts about the value of work that they have done.
Such doubts cannot be answered by telling people the answers, or even showing them how it's done - the only way forward is to have them do it themselves, so that they experience the results and value.
That's what this workshop will do, and participants are invited to bring their own documentation and documentation problems with them. (I'll use Django's own documentation for some examples, and I hope that this will be an opportunity for prospective Django documentation contributors.)
The approaches, principles and practices of this workshop comprise a systematic toolbox for working on documentation, that attendees will apply to real work in the session, and can take away with them afterwards.
Some of them may already be familiar from https://diataxis.fr/how-to-use-diataxis/ and other contexts; they include concepts such as iteration, organic workflow and sustained momentum, and practices such as identifying needs and actions, direction-finding, judging progress and understanding when to stop..
I am a Director of Engineering at Canonical, where I lead documentation practice. I enjoy helping organise community conferences for Python and Django. That includes multiple editions of DjangoCon Europe, as well as the first editions of PyCon Africa and DjangoCon Africa.
I also enjoy helping people and open-source projects improve their documentation.