Holistic Approach to Ubuntu Documentation

Registered by Jason Warner on 2012-04-25

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? .)

Blueprint information

Status:
Not started
Approver:
None
Priority:
Undefined
Drafter:
Jo-Erlend Schinstad
Direction:
Needs approval
Assignee:
None
Definition:
New
Series goal:
None
Implementation:
Unknown
Milestone target:
None

Related branches

Sprints

Whiteboard

[mpt] It's not clear whether this is referring to documentation for users (e.g. help.ubuntu.com), contributors (e.g. wiki.ubuntu.com), or application developers (e.g. developer.ubuntu.com). Maybe it's about all three, and maybe there should be unobtrusive signposts between them. But overall, it's important for them to be distinct. For application developers, see <https://blueprints.launchpad.net/ubuntu/+spec/community-q-upstream-appdev-docs>.

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.