I’m really happy to see this conversation.
I’ve very recently joined Canonical as Director of Engineering, for documentation, and the concerns and ideas expressed here align very well with my ambitions for documentation at Canonical more widely. In fact you’re all somewhat ahead of me.
I think the first thing to say is that I recognise the concerns raised here. That concern is shared. Canonical wants to address a raft of concerns around documentation, and you will be seeing changes.
To make the right changes, to execute them effectively and to make them stick, we’re making a serious investment in documentation. This includes strengthening our documentation team, developing skills and expertise and making it a priority internally.
I think documentation and community have a special relationship in open-source software, and that documentation and the way it’s done help express community values even more than the development of code. I think that by paying attention to our documentation we help strengthen and empower our open-source community.
Here are a few of the things that are already in motion, or will be soon:
Adoption of the Diátaxis documentation framework
I saw that Ian Weisser has already suggested adopting the Diátaxis framework for Ubuntu. It’s what Canonical will be moving towards for all its documentation.
As I said, you’re ahead of me, but I want to understand Ubuntu’s documentation needs in order to see how well they might be served by Diátaxis.
We’re running regular training workshops within Canonical to improve documentation skills - one thing I’ve already discussed with the community team is how we can make these sessions available to community contributors too. I hope you - the Ubuntu community - are interested in this.
The training aims to provide contributors with a better understanding of documentation and how it works, and to empower them to dive in to make changes and improvements with confidence.
For community contributors, we’re looking at ways of making completion of this training something that’s formally recognised, at least within the Ubuntu ecosystem.
I’d be very interested to know your thoughts on that, and its value to you personally.
Team and community building
I think that both of the above will help, but they’re not the whole story. I know that @madhens and @rhys-davies have this on their minds. I hope we can help them build up strength and purpose around documentation in the Ubuntu community, that involves more people, and also has value beyond documentation itself.
Documentation tools and technology
One of the things we want to look at, a little further down the road, is the documentation tooling and the processes it enables. The good news is that there are many well-proven options, and also that choosing one doesn’t necessarily preclude useful integration with another (for example, using a friendly web-based editor as an additional frontend for a documentation repository maintained in VCS).
It’s important for community members to have their say in all of the above. However it’s really clear to me that both within Canonical and in the wider Ubuntu community documentation is valued by people, and that there’s a strong desire to do it better, and I hope that I can help to achieve that.