Ubuntu documentation mentioned in article

[Phil Bull]

Hi Rich,

On Sat, 2007-04-28 at 10:18 -0500, Rich Johnson wrote:
> Information Week wrote up a battle of the desktops between Ubuntu and Vista. 
> It was a very fair review in my opinion and they even wrote about our work.
[...]
> This just goes to show how important Topic Based Help really is. The new Vista 
> documentation and the way they have it setup is absolutely brilliant. With 
> every piece of system documentation there is one of those "didn't find it 
> here, search here" dialogs that will usually find the information for you. 
> Similar to the Visual Studio help dialogs.
> 
> They are right about our wiki's, and our system documentation as well. We need 
> to use this as motivation to crank out some killer documentation, and try and 
> get together and figure out how to clean up and restructure the wikis as 
> well. Yesterday during my Open Week talk everyone had the same comment "what 
> is the difference between the wikis? why so confusing?".
> 
> Time to hit the blogs I think and try and draw in some more help.

I've been thinking about this recently too [1]. It seems that most of
the problem is to do with structure; we need to find some way of
managing topic categorisation, different languages and different
versions of Ubuntu/Kubuntu/etc. I don't think that we can do this in a
satisfactory way with MoinMoin, at least not without modifying it in
some way.

Another issue, which mdke pointed out in a bug somewhere, is that of QA
and making sure that the documentation is useful and correct [2].

Concerning the difference between wiki.ubuntu.com and help.ubuntu.com, I
think we should turn w.u.c into the 'Developer' or 'Community' wiki,
where *only* specs, meeting logs, release schedules and similar go. Any
documentation which users are likely to want should *all* be on h.u.c
IMHO, and the w.u.c main page shouldn't really mention user
documentation as much as it does, in order to emphasise this division.
Hopefully that would clear up the confusion.

My thoughts on structuring the wiki docs would be to use the categories
that we have in the system docs, e.g. 'Internet', 'Keeping Safe'.
Everything on the help wiki should belong to a category; for example,
the current 'ADSLPPPoE' page could be moved to 'Internet/ADSLPPPoE'.
This would potentially cause problems with having too many
subcategories, but each category would be well-defined and finding
things should be easier as similar topics would all be in the same
category.

In addition, we could decide on some sort of organisation scheme for
different languages and versions. I think that each language should
probably have a sub-wiki (e.g. help.ubuntu.com/community/fr) if
possible, as this would keep the search results separate and allow the
page names to be localised. This would require more manpower to
maintain, however.

I also think that a document for a specific version of Ubuntu should
just be sub-paged (e.g. 'PageName/6.06') and the version it applies to
could be clearly displayed (using a MoinMoin macro?). Any documents
which contain separate instructions for more than one version of Ubuntu
should probably be split up into separate pages.

With an organised version and l10n scheme, we could even publish the
system docs onto the wiki in the corresponding categories, rather than
having them as separate HTML guides.

Besides all of that, I think some stylistic changes to the help wiki
would be useful. I've made a mockup to suggest some changes[3]. Would it
be possible to stop PageTitlesLookingLikeThis too?

Sorry to braindump, but just to make clear; I am volunteering to try and
implement some of this stuff if anyone thinks it would work!

Thanks,

Phil

[1] - http://philbull.livejournal.com/37933.html
[2] - https://wiki.ubuntu.com/HelpWikiQualityAssurance
[3] -
http://philbull.googlepages.com/Screenshot-CDRipping-CommunityUbuntu.png

-- 
Phil Bull
http://www.launchpad.net/people/philbull