ubuntu-manual team mailing list archive

[Kevin Godby <godbyk@xxxxxxxxx>]

On Tue, Oct 8, 2013 at 6:16 PM, Phill Whiteside <PhillW@xxxxxxxxxx> wrote:
> at present we have separate teams all trying to achieve the same thing. None
> of the teams have enough people... Is it really too scary for us to all pool
> what meagre resources we have in what is called 'man hours' to instead run a
> manual system for 14.04 which is split between "desktop" and "server" ? Each
> can provide links to the other... To me, it just makes sense.

I will briefly examine three forms of documentation for the Ubuntu
desktop:  (1) the system documentation, (2) the wiki documentation,
and (3) the Ubuntu manual.

(1) The system documentation is maintained by the ubuntu-docs team
(primarily the ubuntu-docs-committers team) and is available in two
formats: online at
<https://help.ubuntu.com/13.10/ubuntu-help/index.html> and through a
desktop application (available by searching for 'help' in the Dash).

The system documentation consists primarily of procedures for
performing specific tasks. It doesn't provide much background
information or ancillary information. It assumes the reader knows
precisely what she wants to do and walks her through the steps to
achieve that goal.

The reader must either have access to the Internet or be able to boot
to Ubuntu to read the system documentation.

The system documentation is packaged and translated each cycle.

(2) The wiki documentation is maintained by the entire Ubuntu
community and is available online at
<https://help.ubuntu.com/community>. Anyone can modify or create wiki
pages.

The style of the wiki pages varies wildly. Some wiki pages provide
background information or discussion of a topic while others provide
task-driven, step-by-step procedures for accomplishing specific tasks
or troubleshooting a problem.

The reader must have access to the Internet to read the wiki documentation.

The wiki pages may be updated at any time throughout a cycle and don't
adhere to any particular deadlines.

(3) The Ubuntu manual project is maintained by the ubuntu-manual team.
 The manuals are available as printed-and-bout books via
CreateSpace.com and Amazon.com sites for the cost of printing.  A PDF
version of the manual is available for free download at
<http://ubuntu-manual.org/>.

The manual provides step-by-step instructions for various procedures
(including installing Ubuntu) and also provides a bit more background
discussion of some of the underlying concepts.

The reader must either have access to the Internet to download the PDF
or have purchased a printed copy of the manual.

The manual is updated once per cycle and is translated into a handful
of languages.


Before we assume that all of these documentation projects cover the
same ground, I think we should take the time to define their audiences
and goals.  Each of the projects has its pros and cons.

For example, while the system documentation and the manual cover a lot
of the same material, the manual provides more background information
and screenshots than the system documentation (which is helpful for
beginners). The manual is available in print form for offline reading,
but the system documentation is translated into more languages.

The wiki covers a wider variety of topics, but often contains a lot of
outdated and incorrect information. Not as much of the wiki is
translated to other languages. But the wiki can be updated more
frequently than the system docs or the manual.

One might be naively tempted to simply print out the system
documentation and call it a manual, but it wouldn't be a very good
manual. It's be a collection of procedures with no transitions and
little underlying structure. A reader would find it difficult to read
the system documentation without having a particular question or task
in mind; the manual is much more conducive to arm-chair reading.


Having said all that, these documentation projects do have quite a bit
in common, however. Each of the projects needs to work hard to stay up
to date with the latest Ubuntu developments. Collecting information on
how new versions of software applications and desktop environments
have changed is a very time-consuming and often incomplete task.
Pooling our resources on this front, for example, would be a boon for
all the projects.

—Kevin