{Desktop 12.10 Topic] Holistic approach to Ubuntu documentation

[Matthew East]

On 19 April 2012 02:51, Jo-Erlend Schinstad
<joerlend.schinstad at ubuntu.com> wrote:
> Den 19. april 2012 03:11, skrev Jeremy Bicha:
>> 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.
>
> The point is the exact opposite. We shouldn't split documentation up
> into completely unrelated pieces. That is the problem.

I don't agree with this, and I agree with Jeremy.

The fact that information provided to help users (help.ubuntu.com),
information provided to help application developers
(developer.ubuntu.com) and information provided to help contributors
(wiki.ubuntu.com) could all be given the single label  "documentation"
or indeed "information" is just a matter of language. The three
concepts are so fundamentally different that they justify and require
a completely different approach, different websites and even a
different authorship. It's not useful to think of them as different
aspects of the same thing. They aren't.

This is particularly important for users. We mustn't burden users
looking for help with Ubuntu with the sort of complex and confusing
information that is found on wiki.ubuntu.com or developer.ubuntu.com.
We worked quite hard back in 2006 to separate these concepts out
(https://wiki.ubuntu.com/BetterWikiDocs) and I think it's important
that we stand by it. Furthermore, the type of information being
presented to users is so different to that presented to developers
that it warrants different structure and a different style. As to
authorship, developer material is usually best written by developers,
because they know what they are talking about and have been through
the process of learning about those concepts, whereas it's less common
(albeit not impossible) that developers make good authors of user help
because there the level of knowledge required is different, and the
focus is on the skill of explaining something to a non-technical user
in the most effective way. So good writers of user help are often
non-technical people themselves.

Having said that, I think that you also make a perfectly valid, point
about the validity, quality and process used to updating
documentation. Nothing I have said above is intended to suggest that
we have a good process for user documentation - there is vast scope
for improvement almost at every level, both in the structure of the
user documentation, the quality of it, the number of contributors
attracted, and so on. However, these types of points are entirely
separate from the main point which you make about eliding different
types of documentation.

In relation to quality and process, you give a few specific examples
of pages which are out of date and which are difficult to rely upon.
I've no doubt you could have given dozens of examples. On the help
wiki, we do have a way which has been established of dealing with such
pages:

https://help.ubuntu.com/community/Tag

For example, you mentioned this page:

https://help.ubuntu.com/community/btrfs

You're right that it seems to be drafted for older versions of Ubuntu,
so I've added the "unsupported" tag.

Your point of course would be that when you visited that page, in the
role of a user, you weren't to know that the page could be out of
date. And you're right that it would be useful to discuss whether
there could be some kind of systematic process whereby pages are
reviewed and updated on a regular basis, or whereby users themselves
can report problem pages more easily than they can now. Any such
discussion has of course to take into account the fact that there are
actually not a lot of contributors to documentation. It therefore
needs to be coupled with a separate discussion about how to attract
more contributors.

Such a discussion would be very useful. There are plenty of new ideas
and approaches we could consider with a view to improving the user
documentation.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF