Ways to improve documentation

Documentation
,
1

If you’re familiar with the Ubuntu documentation, community-based or otherwise, we’d like to hear your suggestions. There’s a number of issues with the Ubuntu documentation at the moment, and we’re aware of them, trust me :sweat_smile:

We’re getting closer to having people in charge and making steps toward improving documentation, and once we have them, a backlog of ideas and a list of interested people will go a long way.

Please leave ideas and suggestions in a helpful, action-based, manner. Anything too generic or sarcastic will be deleted. E.g ‘update the documentation’ is not helpful, ideas or suggestions as to how to update the docs or how to break down the problem, are :blush: I’ll start…

For more context, this thread spun out of here: https://discourse.ubuntu.com/t/outdated-documentation/

2

Engage the documentation team. Similar to the recent rebooting of ‘snapcrafters’ at snapcraft.io I think we should put energy into getting the documentation team back up and running with a full cast of characters to work with Canonical documentation people where applicable to assign and prioritise tasks for contributors.

This could be low hanging fruit of the documentation team is still active and I just don’t know, or less low hanging fruit but a great opportunity to try and rebuild that function.

3

Suggestion: Move collaborative documents away from Wiki-like (open contribution) and toward a more Debian-like (maintainer/contributor) model.

One reason that we don’t get a lot of Wiki action is that many contributors don’t feel fully competent in the feature that they want to contribute. (Hey, I just discovered how to do this, and want to share). Or they don’t quite grasp which sections to make the changes in. Or writing in English isn’t their strong suit. Or they simply don’t have an hour-or-two available to figure out all the edits in the page that their change requires, and they don’t want to undo somebody else’s great work. So they write the new document in their blog instead.

We can use the existing tools (like how community.ubuntu.com threads can be mapped to help.ubuntu.com), contributors can make suggestions rather than edits. Others can comment and offer improvements. The page maintainer can drop by occasionally to integrate those improvements. (The current wiki does have many of these features, but they are not obvious)

Part of the Documentation Team’s role here might be recruiting and training and coordinating maintainers.

There’s opportunity for lots of bite-size involvement: A new volunteer might maintain a single page, learning the feature, learning the style, interacting with other community members in the thread, and solving the small problems of readability, updating for a new release, etc.

4

I’m afraid it’s about rebuilding rather than engaging. Some history:

A few years ago the docs team actually worked as a team, with regular meetings and doing docs work together. The mailing list was rather high traffic occasionally, even if a large portion of the discussion was of a meta nature. (People love to discuss what other people should do.)

We had a few sections:

  • Desktop (the official desktop guide)
  • Server (the official server guide)
  • Wiki (monitoring, not really maintaining, the Community Help Wiki)

The server guide is now maintained by the server team. The people focusing on the wiki have moved on to other things.

The desktop guide is what’s left as a community maintained set of documentation. It basically consists of GNOME Help plus a few Ubuntu specific pages. It’s made available via the Help button on every (standard-) Ubuntu installation as well as published at help.ubuntu.com. Currently I and dsmythies work together to keep it reasonably updated.

Talking about help.ubuntu.com, there is also a branded version of Debian’s installation guide. I’m not sure how relevant that guide is today, though, given the recent work on the Ubuntu side with improving the installer.

As regards wiki.ubuntu.com, various tutorials, etc. they have never been under the docs team umbrella.

5

Suggestion: Adopt a Diátaxis Framework, including non-Canonical-hosted documentation.

“Diátaxis Framework” is a fancy name for separating the four types of documentation that have different audiences and different functions: Tutorials, HowTos, Discussion/Explanation, and Reference.

Some of this documentation is hosted on the Wiki, some is on Discourse, some is on readthedocs, some is on YouTube, some is on AskUbuntu, some is upstream, and some is scattered across hundreds of blog posts. Folks are creating lots of documentation; they’re doing much of it other places instead of the Wiki.

The framework suggests that some documentation is appropriate for the Wiki, and some is not.

We can use this framework to prioritize the kinds of documentation that we want for our users, avoid duplicating appropriate documentation that is already hosted elsewhere, and to guide hosting decisions for regular updates.

Example: If a good how-to-install-Ubuntu 20.04 tutorial is on YouTube, then we don’t need to be in a hurry to recreate it in another venue. We might want to ping that creator to upload an updated video for new releases.

Example: If a good discussion/explanation of the features of the Subiquity Installer is located only on one developer’s blog, then we might engage that developer for regular updates (or suggest they copy the post from blog to the Wiki or to Discourse).

I think this kind of framework can eliminate some Wiki Paralysis. You’re not writing a document for all possible users: It’s either a simple checklist for beginners or a lengthy discussion for advanced learners. Separate documents will be easier to maintain, one way of addressing documentation bitrot.

I think it also addresses some of the egad-what-are-we-going-to-do-about-the-huge-old-wiki question. It’s a framework to evaluate what should be in wiki format, what is better hosted non-wiki on other Ubuntu sites, and what is better hosted outside of Ubuntu infrastructure entirely.

There can many bite-sized volunteer tasks, entry points for new volunteers: Update the checklist for XYZ, ping these YouTube creators for the new release, etc.

1 Like
6

I think this is a start, but if we are going to do this, we should really look at doing it in a way that solves more than just the Ubuntu docs issue.

A system that streamlines documentation tasks is really needed here.

  • allow bugs to be reported, sugestions and updates made
  • Allow versioning
  • Works to deal with man pages for packages (and automates the process) and other documentation

While its nice to link to the world, that is a lot of potential rot we can’t control. So we would need to have a way of identifying the important stuff and bringing it into something we can control.

We need to make it easier to identify what docs need help, what needs to be documented and where existing documentation lies.

2 Likes
8

I was just about to mention diataxis, and how this framework can guide not only our overall approach to documentation, but the initial stage of sorting where things should live. You did a great job of exploring of how we could put this into practice, and I think if your method described in the post was integrated with a useful index/guide, it could get the process of improving our documentation on a solid foundation more quickly.

I am very curious to hear what others think about using the diataxis framework in some of this initial sorting work, and get us over our Wiki Paralysis, as Ian so eloquently put it.

9

The only caution I would offer on diataxis is that its categories can be limiting. In another post I identified types of documentation that is not really part of diataxis, but is none the less necessary. So while I think it is a good base, any system we settle on should be able to expand on that base. I do agree the system should also have an index/guide type feature, as well as a good, well thought out tagging system, with the ability to easily edit tags.

I would also like to see doi integration from the start. Both automated creation of doi number for the documents in the system, and automatic linking of doi references.

2 Likes
10

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.

Training

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.

6 Likes
11

Any update on any of this?