Expanding the documentation

[Matthew East]

Hi,

On Sat, Jun 7, 2008 at 6:40 PM, Nick Ellery <ellery.nick at gmail.com> wrote:
> -- Reporting Problems.  A section like this would assist in bug triaging and
> fixing, as links to debugging specific packages could be provided.  Pages
> like Reporting Bugs [1] could be imported so people are able to find them
> with ease.

The thing about this is that it's part of contributing to Ubuntu,
rather than being user help (at least in theory). That hasn't
generally been a subject which is suited to the desktop help system,
although of course it is something that we communicate to our users in
other ways (e.g. through the firefox startpage, the Ubuntu website and
so on). We can always discuss other or better ways to do this, but
personally I'll need a lot of convincing that this has a place in the
desktop help system.

(Of course, I understand that sometimes advanced or power users may
report or search bugs as a way of fixing problems with their system,
which in turn is a way of getting help. However it's interactive help,
rather than documentation, and if anything belongs alongside the other
types of getting interactive help, like forums, mailing lists and so
on.)

> -- Installing New Themes.  Many users are stumped when it comes to
> installing community provided themes from sites such as gnome-look.org.  A
> detailed description on how this works could help many.

This is certainly something that we could include in the "Customising
your desktop" section of the desktop help.

> -- Installation Guide [2].  The installation guide exists, but should be
> moved from the bottom of the page, where it is incorrectly labeled, to the
> Desktop Documentation category.  Currently, you can find this at the bottom
> of help.ubuntu.com, where it labels it as 'Installing Ubuntu via the
> alternate CD'.

I don't understand this. In what way is it incorrectly labelled? That
guide *is* about installing Ubuntu via the alternate CD. I certainly
don't see this guide as part of the Desktop Documentation, first
because it's a secondary way of installing Ubuntu (the desktop CD is
the preferred solution) and secondly because someone running an Ubuntu
desktop doesn't need to know how to install Ubuntu, they have it
already.

I think what you're raising indirectly is the fact that a guide to the
secondary way of installing Ubuntu appears on the homepage of
help.ubuntu.com, whereas a guide to the primary way doesn't appear. A
better way to present installation documentation would be to use this
page from the help wiki -
https://help.ubuntu.com/community/Installation - and link to the
alternate CD guide from there.

> -- Multimedia.  A section providing information on pre-installed graphical
> applications such as GIMP, especially links to the official documentation
> would be good.  This could be expanded from musicvideophotos, and also
> include brief information on applications such as Sound Recorder, video
> editors, audio editors, and desktop recorders.

The GIMP is documented already in the desktop help, in the
musicvideophotos document
(https://help.ubuntu.com/8.04/musicvideophotos/C/photos.html#photos-editing).
Probably this covers most of the tasks that ordinary users will want,
although I agree that it would help to include a link to more detailed
GIMP documentation for more advanced tasks.

> -- Perhaps a troubleshooting guide, similar to the one in the Official
> Ubuntu Book would be good.  Issues with X, dpkg, and the like could be added
> here

Troubleshooting information for common problems is definitely helpful,
as long as we keep in mind the basic rule that the system
documentation is aimed at desktop users, and avoid references to
strange names like dpkg :) and avoid documenting complex terminal
operations unless absolutely necessary to fix a serious and common
problem.

> -- There is no official guide for editing GRUB, as well.  There are many
> good tutorials on the web, and cleaning up GRUB is something that many new
> users will want to do.

I don't think this is a task that we should document. It's too
advanced and may result in users' systems becoming unbootable.

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