Compassionate doc

by Bill Wear on 28 July 2022

The wonderful people that make up Canonical have a goal: We want to be the best open-source company in the world, period.

I think it’s also a goal that’s espoused by our management, but that doesn’t take away from the fact that every person who works here probably wants to make the world a better place, probably through open-source software. It’s in our blood.

I’m really here because I want to write great documentation. Technical writers sometimes enjoy a rather low standard of excellence, to be honest. I’m very happy when someone finds a tiny little mistake in an obscure code example near the bottom of a long article; that means they’re reading it, and that’s often the main criteria of success for documentation. But that’s not the main criterion for me.

Am I holding your attention?

We have lots of initiatives going on within Canonical as we grow, and that’s fantastic. Within the doc realm, we have the Diátaxis guidance, which has helped us organize our thinking and writing. Within the development teams, we have various open-source components that we didn’t write and don’t own — and that’s valuable, because that’s how open-source is done. And within our field organizations, and in my own developer advocate work, we have connections to users and developers, who give us quick, useful, and constructive feedback.

Now, here I am, trying to integrate that treasure-chest of guidance, whilst building documentation that will actually help our readers. At first glance, it might seem like a chore, but in fact, it’s a very wonderful place to be. And this is where, dear reader, I need your help.

As a technical author, I’ve always felt that my primary responsibility is to hold my reader’s attention long enough to teach them something. The art, of course, is staying on topic. My friend Jack puts it this way: “To truly explain how to bake a cake, you must first invent the universe.” My readers didn’t come for a physics lesson, but gauging where they sit on the spectrum of relevant knowledge is sometimes challenging. And I want everybody to get what they need.

Defining “compassionate documentation”

Here’s where I need your help, readers. I am trying to integrate the following amazing feedback into one approach to better documentation. Understand that I’m condensing this feedback and adding my own sensory experience to it, but not in a way that distorts the core message:

• the doc is not narrative enough; it used to be, but it’s become too sterile and cookie-cutter.
• we bundle some open-source products, and some of those have bad / limited / incomplete doc; we chose that product, so we have to take some responsibility for it.
• MAAS involves a lot of peripheral learning (e.g., networking, BMC, and packing OS images for deployment); there’s no one place to go to learn all this.
• some of our MAAS users and developers aren’t adequately prepared for the level of knowledge needed to make MAAS a success, through no fault of their own; perhaps they inherited the product, or they were thrust into the job because they were available, or they were the most knowledgeable person in their organization.

The MAAS team discussed this problem in open forum earlier today. What’s critically important about this, to us, is the phrase, “the best open-source company“. Being the best means making choices about which FOSS cultural stances to adopt, and which to reject.

Since the early 90s, I’ve been working with various open-source projects, often doing some form of documentation. Sometimes, I haven’t been comfortable working with an open-source team (or continuing to work with them) because of some of the common attitudes toward end users:

• “If the users don’t understand the underlying technology, we don’t need them anyway.”
• “This stuff isn’t perfect. You need to figure things out, Google is your friend. Good luck.”
• “I am not your high-school teacher.”
• “Don’t get it?  So sad for you.”
• “Here it is. If you can use it, great. If not, oh, well.”

The theme here can be summed up as, “Users aren’t my problem“. Or put more specifically to my own situations, I abhor the idea that “User understanding isn’t my problem.”

I don’t subscribe to that. Being the best open-source company in the world means having compassion for the users. Writing the best open-source documentation means having compassion for user understanding: understanding of our products; understanding of the FOSS we bundle; and understanding of the underlying principles needed to successfully apply and use the product. That’s what I would call, “compassionate documentation”.

What is our responsibility?

This idea, of course, opens up a question of responsibility — especially responsibility for other people’s products and ideas. We already have a habit of taking over the committer role for products we bundle that are orphaned by their creators. That’s responsible development. But there’s a thornier problem that creeps up when we try to take responsibility for documenting other people’s active products, or even educating our users on fundamentals.

This difficult problem involves two things that are highly respected in the open-source community: ownership and prior art.

Ownership means that we have to be careful not to overstep the original creator. If they have documentation, and that documentation is lacking in some way that affects our product, we are responsible for clearly explaining things. Out of respect, though, we have neither the right nor the responsibility to rewrite someone else’s documentation — especially not for reader convenience or narrative flow.

Prior art means, essentially, that there are plenty of other people, all smarter than us, who have previously explained the principles behind our fundamental technologies. Prior art is, in fact, the absolute cornerstone of FOSS: we respect your work, give you credit for it, and respect you as the creator.  Extending this to technical writing, this means respecting writers who have come before, even if their books aren’t under an open-source license.

We really should guide you to existing resources, perhaps even pinpointing specific, relevant material. Trying to rewrite or summarize material that’s already been (often beautifully) explained is a common thing on the Internet, but it doesn’t offer the appropriate respect for existing sources.

Soliciting ideas

We have some seedling ideas, but we’d like to share them with you, dear reader, and get your feedback and suggestions. Here are the salient points:

• We would like to do whatever is necessary to hold your attention while we help you learn what you need to know. We can’t fully customize that experience to every reader, but we can always improve.
• We would like to take responsibility for any relevant, technical explanations that cannot be clearly resolved by other sources. If we’re using PostgreSQL in a specific or unique way, we will document everything that might be confusing or unclear by reading just the PostgreSQL documentation alone.
• We would like to take responsibility for any documentation that is unique to our product, trying to make sure it’s focused, complete, and comprehensible.
• We would like to moderate our use of structural documentation ideas, such as Diátaxis, page formats, and navigation tools — and moderate their use in a way which both allows the narratives to flow and reduces your need to change context when trying to learn or accomplish something.
• We would like to take responsibility for helping you more effectively use owner documentation and prior art to lift you up within the disciplines that directly relate to MAAS, both in terms of knowledge and understanding.
• We want to do all of this in a way that offers appropriate respect to those who’ve gone before; that is the spirit of FOSS.

We’d like to have your feedback. We have put some thought into this, but ultimately, our goal is to be able to write documentation that appropriately holds your attention and provides you with the information you need in the most appropriate way.

Please tell us what you think. We’d truly like to know.