{Desktop 12.10 Topic] Holistic approach to Ubuntu documentation

[Jeremy Bicha]

On 18 April 2012 20:39, Jo-Erlend Schinstad
<joerlend.schinstad at ubuntu.com> wrote:
> 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? .)
>
> Jo-Erlend Schinstad

Your topic mixes developer docs, entry-level user docs, and "power
user" docs. Each of those needs a different approach and I think it's
simpler to tackle them as three mostly separate things. Also, if
you're going to discuss documentation, you should probably include the
docs team (CC'd now) as that's where people interested in that read.

Thanks,
Jeremy Bicha