This is Part 1 in a series about the Discovery Docs initiative, which I will present about in my upcoming GUADEC talk.
A long time ago, in the days of bonobos and fishes, GNOME documentation was written as long, monolithic manuals. We split these beasts into digestible pages as best we could (which is to say, poorly) and hoped for the best. Then we had an idea. What if we actually controlled the granularity at which information was presented? What if, instead of writing books, we wrote topics?
And so we did. We weren’t the first software project to make this shift, but we were early on the curve, and we did it radically. While many help systems still try to shoehorn topics into a linear structure, our help focuses on creating a navigable web of information.
The question of how big the topics are — how big the chunks on the web are — is entirely up to us. For the most part, we have chosen small topics with the least amount of information we could get away with. The reasoning is that users can find quick answers to questions, and if they want to learn more, we have extensive cross linking. Our topics have mostly followed the familiar trichotomy of tasks, concepts, and references. Our documentation is deliberately excruciatingly boring.
Fast forward. For the last six years, I’ve had the privilege of getting paid to peek inside various open source documentation efforts. I’ve advised people on forming a basic content plan, and even made an attempt at templatizing content plans. Aside from the obvious user goals and user stories, one of the things I ask is to define the project goals. What do you want to happen as a result of your hard work on your documentation? Yes, of course you want users to accomplish their own goals, but what else? Here’s what keeps coming up:
- Attract new users.
- Create experienced users.
- Create enthusiastic users.
We want users. Even when there isn’t a profit motive, users are a project’s lifeblood. And we want those users to be experienced — not necessarily experts, but experienced — because you retain people better when they feel invested. And we want those users to be enthusiastic, to love our software, because enthusiastic users help us attract even more users, but also, enthusiastic users are where we find future contributors. Enthusiasm is critical for the long-term success of open source software.
Boring documentation fails these goals. It succeeds elsewhere, but not here. So instead of focusing on quickly answering simple questions, I propose we focus our documentation on learning, exposition, and discovery.
In this series, I will explore ideas on how we can write differently, how we can present information differently, and how we can better position our documentation to help users discover and enjoy the software that we make, use, and love.
