Re: Fedora User Guide

[Paul W. Frields]

On Wed, 2005-08-24 at 10:50 +0530, Rahul Sundaram wrote:
>  Andrew Hudson wrote:
>  
>  > Karsten Wade wrote:
>  >  > Any questions or thoughts to start?
>  > >
>  > > - Karsten
>  > >
>  >
>  > Thanks for the welcome!
>  >
>  > My initial thoughts on the documentation is that it is perfect for 
>  > established users, i.e., those who have installed a Linux distro 
>  > previously. However, if I were to put my wife in front of two 
>  > computers, one with the docs on screen and one with Fedora on screen - 
>  > she would not really have a clue where to begin.
>  >
>  > Looking at http://fedoraproject.org/wiki/DocsProject/DocIdeas I quite 
>  > like the look of the Fedora User Guide - this could be a crucial 
>  > document to help new users ease their way into Fedora & Linux in 
>  > general. I would see it as being written in a conversational style 
>  > rather than a straight 'here are the facts in a particular order
>  
>  
>  I am not fond of the "user guide" name. It isnt specific enough for my 
>  taste. If we have a system administrator guide tommorow, it would like 
>  those people arent users of Fedora. If you are writing about the 
>  desktop, call it a desktop guide. It is what it is 
Yet this nomenclature is commonly accepted throughout the tech industry,
and therefore going against it may be confusing when people are trying
to assess what kind of skills they have learned.  I think a good way of
looking at the problem is by drawing the dividing line at the point
where you require the root password.  The User Guide should be developed
parallel with the Administrator Guide.  People can easily get their
hands on both, and there is absolutely no reason why they couldn't
cross-reference each other.  

We need to think about this documentation, as Tommy Reynolds so
helpfully pointed out in some other thread, as more than just serving
hobbyist home users.  Consultants and professionals may also find value
in these documents and they need to serve those needs as well.

Any task that requires the root password should be in the Administrator
Guide.  This simplifies life for sysadmins who want to distribute the
User Guide in an office to the customers (users) they serve.  It is not
helpful to those sysadmins for their users to start reading about
administrative tasks that are out of their purview.  Any reader who
wants to learn can be expected to pull down as many guides as she wants
to learn how to run her system fully.

If we take the "Desktop Guide" idea to its logical conclusion, the
Installation and any Security Guides should be included in it as well.
That makes for a large, unwieldy, and awkward document to manage.  Even
though Guides are larger, they should be split along logical lines, and
I think the model above provides an easy answer to doing that.

Does this mean that home users will have to refer to more than one
guide?  Yes, but if the Web site and/or pointer materials have simple
instructions for which guide to consult, that is not a problem.  For
instance:

"If you want to learn how to install a Fedora system, consult the
Installation Guide <URL>."
"If you want to learn how to perform common tasks on your Fedora system
or change your personal user preferences, consult the User Guide <URL>."
"If you want to learn how to change global system settings or administer
network services on your Fedora system, consult the Administration Guide
<URL>."
"If you want to learn how to further secure your Fedora system, consult
the Security Guide <URL>."

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.  This would
help the brand-new user know when they need to look at the User Guide,
and when to look at the Administration Guide.  This type of setup worked
very well in the original Red Hat guides, and there is no reason we
should not follow a model that works well.

-- 
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/