Expanding the documentation

Phil Bull philbull at gmail.com
Wed Jun 11 17:21:02 UTC 2008


Hi Matt,

On Sat, 2008-06-07 at 21:55 +0100, Matthew East wrote:
[...]
> I think we should definitely find a way for the "official" docs to
> interact better with the wiki docs. Maybe we can move forward in this
> release cycle with the idea of merging the two, and have a single site
> which explains to users how reliable each page is.

The official docs could be imported into part of the wiki using this
script [1], if we made a few improvements to it. We can then use
Wikipedia-style banners at the top of wiki pages to give warnings about
the reliability of information. The latter would simply be a matter of
including one of a set of pre-defined pages using the Include() macro,
and would be absolutely trivial to implement.

> > I'm also interested in starting out the Troubleshooting Guide, and have some
> > ideas that hopefully aren't too technical.
> 
> Great, look forward to seeing your contributions. One thing I would
> say is that I don't think troubleshooting information should be in a
> separate "guide", but rather should appear in the relevant section of
> the documentation that deals with the relevant subject matter. For
> example, troubleshooting package installation problems should be in
> the "Adding and Removing Software" section, internet connectivity
> problems in the "Internet" section, and so on.

I agree, and I'd really like to see the inclusion of more
troubleshooting information. I spent an hour or two this afternoon going
through posts in the Ubuntu Forums to try and identify the most
commonly-asked questions. You can see a listing of what I found here
[1]. Here's a summary of the sort of questions people seemed to be most
interested in:

      * Partitioning
      * Changing screen resolution
      * Sharing files over a network (Samba)
      * Uninstalling Ubuntu, reinstalling Windows
      * Dual-booting issues (e.g. Windows won't start after installing
        Ubuntu)
      * What to do when apt/dpkg breaks
      * Problems playing DVDs, streaming files, certain audio/video
        formats
      * Stand-by, hibernation and shut-down issues
      * Getting Wacom graphics tablets working
      * Getting certain wireless chipsets to work (especially Broadcom
        ones)
      * Problems with sound (these were *very* common)
      * Getting NTFS/FAT volumes t mount automatically at boot time

More details and specific examples can be found in the document I linked
to.

Some of these issues are already covered by the documentation, or would
be best off being explained on the wiki. However, I think that there are
definitely a number of candidates for inclusion/improvement to the
system docs in there.

Thanks,

Phil

[1] - https://wiki.ubuntu.com/DocumentationTeam/Ideas/ArticleToMoinDesc
[2] - http://philbull.googlepages.com/CommonQuestions-UbuntuForums.pdf

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





More information about the ubuntu-doc mailing list