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 -- ubuntu-desktop mailing list [email protected] https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
