{Desktop 12.10 Topic] Holistic approach to Ubuntu documentation

Jo-Erlend Schinstad joerlend.schinstad at ubuntu.com
Thu Apr 19 06:19:25 UTC 2012


Absolutely. Indeed it should. Not only for different types of users, but
for different "trails" as well. Again I use Unity as example. Suppose
you want to start developing. You've covered the basics of the language,
and now you want make something you can show your friends. So you do to
the docs page > developing > Python > Desktop > Unity. There you find
the Unity Specification 1.0 Documentation, with Indicators, Launcher,
and everything. You learn how to make lenses and scopes, and there's
lots of them to make in your area, so you just keep going and become
really good at it. Then you begin to wonder how it works under the
scene. So you go to the next level, which is the DBus architecture.
You're still on the same trail, mind you. So you lean how the DBus
bindings work in Python and then you move on to the DBus Unity API
itself. That's the exact same document you'd end up with if you'd
started with Vala, because after all, it's the same thing. If you've
followed the Python trail already, you'll just get the "Oh, I know
this!" feeling, which isn't a bad thing.

So the main documentation tree might be grouped in libraries and then
under language, as is the case on dev-u-c now, but to the user, it'll be
presented by their interests, as trails. The documentation isn't just
something that comes with the tools. The documentation itself is its own
product with its own goals. 

Here's an example for you; I recently switched to BtrFS in Precise. I
needed to learn, and I ended up here:
https://help.ubuntu.com/community/btrfs. As far as I can tell, there's
nothing particularly wrong with that information. But then, this stuff
is new to me, so how would I know? It doesn't inspire confidence.
"Ubuntu-specific subvolume layout in 11.04 and later"? I'm using 12.04!
But I'm very familiar with this, so I scrolled down towards the bottom
of the page to see when it was last updated. Just a few days ago. Nice.
And I can see the page history. On my way there I noticed that most of
the information is for 8.10! This is a filesystem we're talking about. I
really need to be confident about this information, and the mere mention
of 8.10 makes me suspicious.

This page was marked out of date nearly four years ago:
https://wiki.ubuntu.com/UbuntuOnMac. Why does it even exist? I assume
it's simply because noone has the overview to systematically make sure
pages like that is either updated or deleted. If noone has an overview,
then it's difficult to attract contributors as well. Specific tasks
makes it much easier. And by update, I don't mean adding new info on
top, leaving older info below. One page per version. Reviewed. Obviously
Valid.

Facts aren't good enough anymore. We need to design documentation for
the user. And that can't just be about deleting old wiki pages. We need
a goal. A new way of thinking about documentation as a whole.

Jo-Erlend Schinstad





More information about the ubuntu-doc mailing list