[CentOS-docs] Comments? HowTos/CentOS5ConvertToRAID

Wed May 13 13:02:00 UTC 2009
Scott Robbins <scottro at nyc.rr.com>

On Wed, May 13, 2009 at 08:20:07AM -0400, Phil Schaffner wrote:
> Ed Heron wrote:
> ...
> >   Thanks.  Writing documentation is always a balancing act between not 
> > putting enough detail in because it seems intuitive to the person who does 
> > it every day and putting too much in with the effect of it being too 
> > pedantic.

After years of cursing out documentation, I always go with the better
too much than too little information.  

Depending of course, upon what you're documenting, it should allow
someone without experience of the software to use it, and not have to
google to figure out what you meant.  I think of it as being considerate
of the reader's time.

Often, I find the difference between BSD docs and Linux docs, the
difference between something written for the busy sysadmin and something
written for the hobbyist who has all day to go searching around for the
missing pieces.  

(The above of course, is a BROAD generalization, but I try to keep in mind
that the reader probably has better things to do than research something
I wrote, which is, no doubt, something they discovered while trying to
understand something in the official docs.)   :)


-- 
Scott Robbins
PGP keyID EB3467D6
( 1B48 077D 66F6 9DB0 FDC2 A409 FA54 EB34 67D6 )
gpg --keyserver pgp.mit.edu --recv-keys EB3467D6

Giles: Might I have a word? 
Buffy: Have a sentence even.