Fedora User Guide

[Paul W. Frields]

On Wed, 2005-08-24 at 19:21 +0530, Rahul Sundaram wrote:
> Paul W. Frields wrote:
> >On Wed, 2005-08-24 at 18:32 +0530, Rahul Sundaram wrote:
> >>>Although the line of "root password required" is (IMHO) a great place to
> >>>divide the guides, there may be a call for a *short, sweet* "Getting
> >>>Started Guide" that discusses only the MOST basic tasks and talks about
> >>>the differences between the roles of user and administrator. 
> >>>
> >>It has been pointed out before but any tool that requires a password for 
> >>a desktop functionality is broken. We should divide by functionality. 
> >>Not by whether it requires a root password or not
> >
> >Can you give some examples?  I am trying to figure out which tools this
> >would apply to.  I don't recall getting password prompted for anything
> >which *wasn't* a global system setting change that would affect other
> >users on a managed system.
> >
> I was talking about a general idea, not specific bugs
> 
> http://mail.gnome.org/archives/desktop-devel-list/2004-June/msg00161.html

Havoc is talking about usability improvements (and 12 months later, in
FC4, we can see the effects of work on that front) and how to organize
preference tools.  When he says a root password does not drive
development of the user experience, he's right.  But documentation
discusses the system *as it exists*, not *how you wish it was*.  Moving
a piece of documentation from one Guide to another doesn't impact on the
usability of the system, it's just a link (whether a hyperlink or a
conceptual link) from one page to another.

Nevertheless, here's the upshot, that DocBook XML lets us easily grab
<section> modules and drop them from one doc into another.  As D-BUS and
a few other enabling technologies change the interaction that a "normal"
user has with the system, sections can migrate from an Admin Guide to a
User Guide easily.

If running a specific tool requires the administrator password, a
managed user (again "managed user" means "user in the workplace who
doesn't necessarily have root") is not going to have access to it.
Telling that person how to do something she is not allowed to do causes
more aggregate frustration than telling readers "refer to the Admin
Guide for information on how to do XYZ."

Again, cross-referencing solves the problem for home users and other
people who own their system.  If the developers make a mistake in
deciding to keep a user from making a perfectly reasonable system
setting change, it has a far-reaching impact.  And if the control tools
for changes a user *can* make are organized wrong, the system is harder
to use.  That's Havoc's point.  But using the root password as a
dividing line for where to document a tool is still reasonable, since it
follows the generally accepted methods of technical documentation.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050824/e5983b0f/attachment.bin