>I think that stating with the Programmer's manual,
Agreed. How about others ?


----- Original Message -----
From: "David Woyciesjes" <DAW@yalepress3.unipress.yale.edu>
To: "'maximum entropy'" <entropy@tappedin.com>; <of@linkedwith.lv>
Cc: <port-i386@netbsd.org>
Sent: Thursday, July 19, 2001 17:07
Subject: RE: NetBSD docs


> I can help with this, by doing proof-reading, and checking for
readability.
>
> ! >> You will find many of the BSD documents in /usr/share/doc
> ! >It's common answer for BSD. It's not sufficient.
> !
> ! I didn't say it was sufficient.  I said it would be a starting point.
>
> Either way, I think that starting with the existing docs is the
> right idea. I think that stating with the Programmer's manual, the to
> SYsAdmin, then finish with the Users Guide should be the way to go. This
> way, everyone in the documentation team will get a good understanding of
the
> system, and will have an easier time explaning the info for the SysAdmin,
> then the User. Make sense?
> Or should it be Users, SYsAdmin, then Programmers?
>
> ! >> I'm not sure why you think the PRM is a horror.  It would
> ! probably be
> ! >> the easiest since it's essentially just the man pages
> ! (sections 2, 3,
> ! >> 4, and 5) which are rather well-maintained in NetBSD.
> ! >I partially agree.
> ! >I do _NOT_ want to start flame war, but Programmer manuals
> ! should be much
> ! >more theoretical than present
> ! >man pages. No ?
> !
> ! You said "programmer's manual".  I took that to mean "programmer's
> ! reference manual".  If you meant "programmer's supplementary
> ! documents", then I agree.
>
> Actually, it seems like a programmers book would be a mix of both.
> Start off the book (or maybe section) with the facts, the way things are;
> then follow with the theory.
> But if you need to split it, The manual should be the facts, and the
> supplement would have the theory, but strcutured exactly the same way, for
> cross-referencing purposes.
>
> Just my USD$0.02... :-)
>
> ---   David A Woyciesjes
> ---   C & IS Support Specialist
> ---   Yale University Press
> ---   mailto:david.woyciesjes@yale.edu
> ---   (203) 432-0953
> ---   ICQ # - 905818
>