[prev in list] [next in list] [prev in thread] [next in thread] 

List:       samba-docs
Subject:    Re: volunteer
From:       "Andy Oram" <andyo () oreilly ! com>
Date:       2000-07-26 14:41:53
[Download RAW message or body]

Here's one project that would take some work (and not particularly exciting
work) but could improve Using Samba a lot for online use.

To bring everybody up to date, I am the editor of Using Samba at O'Reilly.
Although Dave and the other authors didn't write it with online use
specifically in mind, I realized as we were talking to the Samba team about
open-sourcing the book that a lot of things about its structure make it
really well-suited for online reference. To make it rock, though, a lot of
cross-links (<A> refs in HTML, <xref> refs in DocBook) have to be added, and
I don't think any automated method would handle a lot of them.

If you're interested, read on. I'll describe how the book could be
cross-linked effectively.

Most Samba options are mentioned in three places in the book:

1. Appendix C, in a quick-ref format that offers plain syntax and one or two
sentences of description.

2. Longer reference sections in various chapters, which give you (hopefully)
"everything you need" to use the option properly.

3. An even more extended tutorial-type discussion (if the option is a common
one) that offers a lot of background and may combine several options that
work together.

The index points to the second mention, the long reference.

What I'd like to see is a link from each option in Appendix C to the long
reference section, and another to the tutorial discussion (if any) that
covers the option in context. Similarly, the long reference section should
contain a link pointing to a tutorial discussion. Perhaps the tutorial
discussion could link to the long reference. In that way people can quickly
get any level and type of information available.

I don't believe I could get resources at O'Reilly for this. The reason is
that it would improve the online version, but not the print version where
all our revenues come from. (The situation may change over coming months, as
we offer books in electronic form in our Safari program, but that's
speculation.)

If anyone wants to take on the task, write me and we'll discuss format. If
anybody wants to be part of the discussion, write me also. I don't think
it's worth involving the whole list--does anybody want it involved?

----------------------------------------------------------------------
Andy Oram  O'Reilly & Associates, Inc.        email: andyo@oreilly.com
Editor     90 Sherman Street                     phone: (617) 499-7479
           Cambridge, MA 02140-3233                fax: (617) 661-1116
           USA                          http://www.oreilly.com/~andyo/
Stories at Web site:
The Bug in the Seven Modules     Code the Obscure     The Disconnected
----------------------------------------------------------------------

[prev in list] [next in list] [prev in thread] [next in thread]