Diátaxis and documentation success workshop, April 2025

Online, free and exclusively for open knowledge projects

I will be hosting a free two-part documentation workshop. This workshop is dedicated to documentation contributors to open knowledge projects, and especially those that already use Diátaxis.

Qualifying projects

Qualifying projects are those whose purpose is to gather knowledge and make it available in a sharable form, for public benefit.

Examples of open knowledge projects: Wikipedia/Wikimedia Foundation, OpenStreetMap, Open Knowledge Foundation and so on.

Not sure if the project you participate in qualifies? Apply anyway and I will let you know.

On this occasion, open source software projects don’t qualify - I’ve run dozens of free workshops for open source projects in the past and will do so again.

Format and expectations

Each session is two hours long. The bulk of each session will be taken up in practical, hands-on exercises and activities. There will be a take-home exercise between parts one and two, that we will review in the second session.

Attendees are invited to bring their real-world documentation problems to the workshop, so that we can discuss them and identify ways to approach them. This discussion is another important part of the workshop.

Attendees are asked to be fully present for the whole of both sessions, with cameras on, and to participate and interact fully. The sessions will not be recorded.

It can bring a lot of value to have more than one participant representing a particular project or organisation, but if necessary I will limit those numbers so that more projects can benefit.

Content

Part one is concerned with the principles of Diátaxis, and the problems it aims to solve. On the basis that learning takes place only through a learning experience, the session will set attendees to work immediately, solving problems that bring the principles into relief. The session will introduce practical tools that can be applied to real-world documentation questions and needs. Discussion will bring together documentation theory and the issues and examples that participants bring to the table.

The take-home exercise is designed to reinforce the learning in the first session, and provide a starting-point for the themes of the second.

The second session focuses on documentation success, in which documentation is seen as an activity as much as a product. It will introduce, demonstrate ways of working that effectively move documentation efforts forward, and ask attendees to practise them. As well as patterns for work, this session will show the (sometimes obscure) patterns that block progress.

Register your interest

Places will be limited in order to ensure that each participant enjoys an effective learning experience. The dates and times of the sessions will be based on the time zones and needs of participants, but I am aiming for two days in late April.

Please complete the registration of interest form.

Once you have registered, I will be in touch as soon as possible to confirm participation and further details about the workshop.

---

My paid employment at Canonical makes it possible for me to offer this workshop without charge.

I am glad to donate my personal time to open knowledge projects. I benefit from many of them directly, and value the social contribution represented by them all.

I have run dozens of these workshops for hundreds of participants over a period of several years, in a variety of contexts. The content, materials, format and delivery have been continuously refined based on that experience.

The nominal value of this workshop is EUR 1680 per person (i.e this would be the charge per person for a workshop run on a commercial basis, though that arrangement would also include company-specific preparation and adaptation of materials, and some 1:1 support/contact time between and after the sessions).