improving online documentation

[Matthew East]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi

* Phil Bull:

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

I think it can be done. In fact, you've pointed pretty clearly to some
ways in which it might be possible in your post.

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

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!!

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

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

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

> 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]. 

Looks very nice - good work.

> Would it
> be possible to stop PageTitlesLookingLikeThis too?

It's certainly possible, although personally I don't think it's a
significant issue.

> 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

Matt
- --
http://www.mdke.org
gnupg pub 1024D/0E6B06FF
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGNZD8tSaF0w5rBv8RAiRYAKCBC+eZs/CM5pvCn40Cg/lN72ihPACfXlE5
NYwuXHZxxX5vYXMGmEHFnGI=
=Xj2R
-----END PGP SIGNATURE-----