organizing book (was Re: cvs commit: doc/en/books/handbook Makefile)

Jeremy C. Reed reed at reedmedia.net
Wed Jun 29 10:18:20 PDT 2005


On Wed, 29 Jun 2005, Justin C. Sherrill wrote:

> Are you thinking of splitting between administrative and user functions,
> as the FreeBSD Handbook did, or something else?

1) Yes, somewhat. The book is too long to print I think (at 824 pages).
See http://sloth.wcug.wwu.edu/~reed/dragonfly/book.dvi.bz2 (633KB). (I use
"xdvi -paper 7x9in book.dvi".)

And it covers some topics that aren't needed (and maybe not accurate)  --
for example look at many examples in the Linux compatibility chapter.
Also, some chapters are too long. And some same topics are covered in
different places.

I am not sure how the book should be split up: by topics or by technical
level. If we do by technical level, we will end up having same materials
covered twice, because the more advanced book will repeat some information
to have a starting point for the discussion. We should probably do by
fine-tuned topics. What do you think?

2) We should make a list of the items that are important for the book and
make sure they are covered. For example, it is missing syslog.conf and
newsyslog instruction.

3) And we should organize the order of the covered topics. We can use a
wiki to make a good outline for one or two books first and decide on it.
(Last year, I helped redo the table of contents, outline of topics, and
tools covered for a later Wiley-published Unix book.)

Also, we can use the BSD cert survey results to make sure the DragonFly
Book covers the topics that the BSD cert survey results cans are
important. (To be officially announced mid-July.) The results indicate
what topics are beginning, intermediate, advanced and also how frequently
used and also other.

And then we could move around the existing content to meet our goals.
(This might be a good time to do a switch away from SGML too -- but maybe
that is too much to do simultaneously.)

4) Also we need a thorough review. We can use a wiki to coordinate who
will review what. We can make a list of all topics -- maybe by page
numbers and/or by webpage chapter sections. (Maybe break down into at
least five pages.) And then ask the entire community to sign up to review
a section or two.

Their feedback can include: technically correct? easy to read? easy to
understand? Beginning or advanced?

Can someone volunteer to make a wiki page for this -- and then
announce to community for help?

Note that two of my goals for helping with this are to learn more about
book publishing in print format and that I want to earn at least some
money from some book sales. (I can't see why anyone can complain if I want
to earn money: the book is licensed to allow this, BSD Mall does same, I
will work hard to improve the book and others can reuse this work for
their own products, I will commit my writing/edits back for others, and I
will provide some of the earnings back to project.)

 Jeremy C. Reed

 	  	 	 technical support & remote administration
	  	 	 http://www.pugetsoundtechnology.com/






More information about the Docs mailing list