Our best foot forward

[Emmet Hikory]

On 11/15/07, Sarah Hobbs wrote:
> How much of all this tutorial stuff is already in the man pages?

    The manual pages contain vast amounts of detail, but I'm not sure
they provide the overview for some of the more general questions.
Further, I'm fairly certain that most complex tasks are not well
suited for man pages, as they often require several distinct steps,
with different tools (for which there are different manuals), for
which the user may need a higher-level guide.

    For a standard configuration, a lot of the information from the
man pages is already encapsulated in default configurations,
maintainer scripts, menu entries, etc. (and it's a bug if it's not).
For a specific package (containing specific applications and man
pages), most of the detail information should predominantly be of
interest for special configurations, and no "tutorial" should be
required (although users of more complex programs may benefit from
reading additional program-specific documentation (which is, again,
rarely the man page)).

    Further, as there is greater support for task- and tag- based
package management, many of the issues related to groups of packages
(e.g. LAMP, build-essential) can be addressed from the package
management tools.  Meta-information would belong in tag and task
descriptions, rather than in manpages, as there is not generally an
associated program for which the user needs a manual: rather the
requirement is for general information on the suite of applications.

    For managed configuration / settings adjustment, it's a matter of
making these interfaces more prominent: most package-specific
documentation is targeted at the unusual configuration, and does not
suggest a simple reconfigure.  I wouldn't expect that additional
documentation would help much here, aside from a general effort to
insure that automated reconfiguration doesn't require knowledge of how
debconf works.

    For those completely general questions (e.g. "Why doesn't my DVD
work?", "How do I use my new gadget with Ubuntu?", "What needs to be
done before I install QuickBooks?"), general documentation is useful,
for which help.ubuntu.com seems to be the right place.

    Regarding tutorial scripts, I'm not sure that the provision of
small shell scripts to automate standard tasks is an ideal way to
address the issue of users not knowing how to do things.  Firstly, in
order for such scripts to be useful to accomplish tasks related to
packages not currently installed, they would need to be maintained
separately, and would be subject to version skew.  Secondly, in the
spirit of doing the right thing, the system should robustly handle as
many cases as possible, referring the remainder to documentation.  If
users are required to manually execute scripts to accomplish goals
they do not understand, this only adds an additional layer of
indirection, for which additional documentation may be required.

-- 
Emmet HIKORY