[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: concerning debian-reference and the necessity for the competitors

On Wed, Mar 05, 2003 at 03:36:07PM -0800, Osamu Aoki wrote:
> I think it will be nice to have following document with clearly defined
> non-overlapping focuses and contents.
> IMHO, current install guide is too thick and deals too much of special
> cases.  Those special cases should be in its appendixes or in a separate
> technical reference.
> 1. Debian (Newbie) Install Guide (50 pages)
>  Focus on CD install with some netinstall information
>  Assumes no previous computer experience
>  Add some dual boot information
>  Up to getting command prompt
>  Basically progeny manual 
>    (up to getting console screen or xdm)
> 2. Debian Newbie Admin Guide (Max 200 pages)
>  Assumes no previous computer experience
>  Basic Unix file system and command tutorials
>  Mix good parts from John's guide and Hands-on Guide 
>    (I like John's file permission things and already stole it)
>  From install to get KDE/GNOME/WMaker/Fluxbox desktop :-)
>  Separation of this from above install guide should help maintainability.
>  Basically progeny manual
>    (Some contents to guide user to set up system after console screen up
>    to running vim, emacs, mozzila, abiword, gnumeric and, not least,
>    working printer with GS along the style of "hands-on guide" is
>    desirable.  No server side daemon things except mail set up possibly
>    with ssmtp or nullmailer.  For this, recommend to initially install
>    exim with option 5. Some information on tweaking .xsession is useful.)
>    I am wondering whether we get response from hands-on document author.
> 3. Debian Install Technical Reference (Max 200 pages, could be web only)
>  All special case scenario should be here
>   tftp install,  
>   special kernel boot disk, PGI installer thing shall be here
>   Assumes basic unix skills.
>   knopix based install scheme
>   This could be a part of Install Guide such as appendix which can be
>   turned off by build script.
> 4. Debian Reference (It's short version, Debian Quick Reference)
>   Collection of all basic administration related tips and hints.  
>   Assumes basic unix skills. 
>   (Most contents in Chapter 2 overlap with FAQ.  FAQ is newer but
>   convenient to have duplicates here.)
> 5. Securing Debian Manual
>   Collection of all security conscious administration related tips and
>   hints.
>   Assumes extensive unix skills.

This is an excellent plan. It is the most user-oriented and 
user-friendly way to approach things. I definitely agree that
the technical details, beyond what's needed for the 90% case,
should go in a separate doc. We don't want to lose them, but
it makes for some deep time-wasting wading for the average user.  

Adam: The Progeny manual is a modern user manual, oriented 
towards first time Linux users, complete with copious screen
shots. It's a very professional manual, which I think we 
would do well to emulate. Starting from an xml version of 
that manual, we can incorporate all the contents from the 
old manual that make sense; except that the contents from
the old manual that are outside the normal user experience,
should go in the technical reference as Osamu has suggested.

The new installer will likely have a graphical interface as the
default option, and a manual with screen shots is the best
way to deal with that.

"The way the Romans made sure their bridges worked is what 
we should do with software engineers. They put the designer 
under the bridge, and then they marched over it." 
-- Lawrence Bernstein, Discover, Feb 2003

Reply to: