Administration-Guide

[Paul W. Frields]

On Thu, 2007-10-25 at 08:31 +0200, Bart Couvreur wrote:
> The current topics list is quite broad, we might want to cut down, the
> further we go. So how do I see the overall picture here:
>       * Part on basic system administration
>               * users / groups admin
>               * yum / yumex (basic stuff and link to the Yum Guide)
>               * partitions, mounting, permissions
>               * task scheduling
>               * (add your ideas here)
>       * Services / servers
>               * basic services management (system-config-services,
>                 chkconfig, service, init.d-scripts)
>               * Basic home-network stuff: NFS, SSH,
>               * describing some broadly used servers (mail, web, DNS,
>                 samba, ...)
>               * (add your ideas here)
>       * anything else
> 
> Just keep in mind that we don't need to cover *all* of this, the things
> we can tackle, we'll get done and the rest will be for later (or others
> to join in).

Sorry I'm late to this discussion.  Here are some guidelines you should
keep in mind while drafting:

1.  Stick to a set of basic assumptions, for instance a default Fedora
installation (i.e. for now, leave out things like yumex, dovecot, or
other nonstandard services/apps)

2.  Focus on showing the user HOW TO accomplish something, rather than
explaining everything you know about a topic

3.  A good guide for the minimum administrative topics would be to go to
the main menu, under System -> Administration, and provide a section for
each sysadmin tool there.  (That doesn't have to be a limit, just a good
starting point.)  It would then be fine for each one to show how to make
any further configuration that is a major use case.

4.  Agree to, and stick to, a best practice for each fundamental
procedure, like using /sbin/chkconfig and /sbin/service for example.

5.  A good outline, even if you're currently just doing a lot of
porting, is a MUST for a good document.  Work on an outline as a
separate task, and don't worry about making anything fit until you have
all the material piled up wherever it makes you happy.  Once all the
material's been gathered, then go back to the outline, check and revise
it, and then start hammering everything into shape.  Without an outline
you risk having a very confusing guide that hops willy-nilly from one
topic to another without any flow.  The flow is what helps a reader
build her skill set -- by starting with simple things, and building upon
them piece by piece.

These are just a few hints that occurred to me.  I will readily admit
that I am no expert in this area, but these are things I try to think
about whenever I'm working on docs.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
           Fedora Project: http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20071030/3f4cfc19/attachment.sig>