I think it's necessary for Ubuntu to take documentation to another level.

When I first started with Ubuntu, I really wanted to learn how it all fit together. I have used computers most of my life so I'm accustomed to reading documentation and I was perfectly willing to dive right in. But it just wasn't that easy, not necessarily because of the information itself, but because of how it was organized and presented. There were no clear starting point and no trails to follow. There were broken links on wikis, and outdated information lying around. Much of the documentation would only use version numbers, and have no easy way to see when it was last updated, or if it had been superseeded. Confusion reduces peoples ability to learn.

To me, this is The Issue with Ubuntu. If we're really going to succeed in taking Ubuntu «across the chasm», then we must make it easy for the curious to become users and for the enthusiasts to become power-users. For this to happen, we need to do something drastic about the way documentation is presented. I think Ubuntu Documentation must:

• Have an obvious starting point
• Lead to the next step
• Be instantly recognizable as valid or invalid
• Be grouped when applicable
• Primarily focused on LTS
• Reviewed for each release (hence the point above)
• Easy to contribute to by reporting issues
• Be not only API docs, but contain readable text.

developer.u-c and help.u-c has improved a lot in this regard, but not enough. Look at this page first: http://developer.ubuntu.com/resources/platform/api/12-04/. As a reader, I can come across issues that I'm not able to read, but will help improve the documentation. I should have a very easy way to report it. There's no way at all on that site, though at the very bottom, I can submit a tutorial.

Another example, look at this page: http://developer.ubuntu.com/api/ubuntu-12.04/python/Unity-5.0.html. Right, but that's Ubuntu 5.0. I was looking for 5.10. Is this still valid? There's no way to know. We shouldn't rely on people to trust that if not stated otherwise, it is valid. This is the web. There are millions of old and unmaintained documents out there. It must be obvious that it is valid. This also helps anyone recognize invalid documentation, enabling them to report it or fix it.

And what if my primary focus is developing an application for LXDE and I want to use only an indicator? In this specific case, I'd use a separate version for the API docs and call it Unity Specification 1.0 for 12.04. Then if there are any changes between now and 14.04, I'd call that 2.0. For versions in between I'd add 1, 2 or 3. So, if there are API changes i 13.04, I'd expect to find a Unity Specification 1.2 and that it would clearly show the differences between 1.2 and 1.0, considering the newest LTS the

In the case of Unity-5.0 for Python above, I'm not sure I'd call that Documentation. That is the convention, but I'm not sure that's what people expects. I'd call that document a Specification. For Documentation, I would expect more readable text, explaining what it's for and how it is used.

Enum: Unity.FilterRenderer CHECK_OPTIONS_COMPACT 4

Right. How do I use it? .)