improving online documentation

[Phil Bull]

Hi Matt,

On Mon, 2007-04-30 at 07:47 +0100, Matthew East wrote:
[...]
> > 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
> 
> Just to be clear, are you suggesting moving anything? The current policy
> is that documentation for users should all be on help.u.c already...

There are two major pieces of user documentation left on w.u.c - the
laptop testing and hardware support reports. I don't know whether moving
these across would be very useful, though. In fact, having an entirely
separate (i.e. non-wiki) way of dealing with hardware compatibility
reports would probably be more appropriate, although this would take a
lot of work for not too much gain.

> As for making the distinction between the wikis clear, it would be nice
> to try and sort this out during the next release cycle. Please read
> https://wiki.ubuntu.com/ImproveWebsiteStructure and add your
> comments/ideas!!

Thanks, I'll add myself to that spec. A quick fix would be to remove the
prominent references to documentation from w.u.c, add a couple of
sentences explaining that it's the development wiki and then change the
logo. I can do this today if you like.

> > 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.
> 
> I agree that we should use categories more. However, we can adapt the
> MoinMoin category system to our purposes and I don't think we need to
> use subpages - doing this allows us to have a page in more than one
> category, which I think would be a common difficulty if we try to put
> all pages in subpages.

I think that using subpages has a few other advantages. First of all,
people can't forget to add a category as easily, because they have to
create the page in a category in the first place. Secondly, the category
is clearly displayed in search results because it is part of the page
name. Thirdly, I think that it would be easier to maintain the docs
because of the clear separation between categories. Lastly, it would
mirror the structure of the system documentation in Yelp, so the website
and system docs would hopefully feel more 'integrated'.

Of course, there are numerous problems with that approach, including the
loss of flexibility in categorisation (as you mention), longer URLs and
page titles, and the difficulty in moving pages if someone puts one in
the wrong 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.
> 
> The current policy is that translated documentation does not appear on
> the documentation wiki, but rather local teams are encouraged to start
> their own localised websites. I think that for the time being this is
> probably the best way to go, given that the main website
> (www.ubuntu.com) isn't localised either.
> 
> (The French pages which you mention on your blog aren't in fact Ubuntu
> pages at all, but rather are translations of the internal documentation
> for MoinMoin, which we can remove).

OK, that seems reasonable for the time being. The MoinMoin docs should
definitely be removed, though.

> > 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.
> 
> +1
> 
> > 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.
> 
> +1 - we'll either have to do this manually or develop the code for
> building MoinMoin wiki markup from xml.

I looked into this, and the DocBook to Moin xslt does a pretty good job
already. The most significant problems seem to be with splitting up
sections in individual .xml files into several pages, and also fixing
links between docs. This is nothing that a small Python script can't
handle, though.

> > 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!
> 
> I would suggest that we develop the relevant specifications for a while,
> because some of the changes are so significant that we are likely to
> need approval from higher levels to go ahead and implement them. When we
> have our ideas clear, we can try and go about obtaining that approval
> and implementing them.
> 
> These specifications have been around for a while, but they have been
> lacking people to work on them and have been held up a bit while we
> concentrated on the new system documentation layout. I think that they
> would make a good focal point for the main efforts during the next
> release cycle. If you're interested in working on them, please add your
> name on the spec.
> 
> https://wiki.ubuntu.com/ImproveWebsiteStructure
> https://wiki.ubuntu.com/HelpWikiQualityAssurance

Will do, thanks.

Thanks,

Phil

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