Subject: Linux-Activists - DOC Channel digest. 93-4-6-14:10
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Thu, 6 May 1993 20:24:12 +0300

Topics:
	 Getting docs printed...

----------------------------------------------------------------------

From: [email-masked] (Andy Oram)
Subject: Getting docs printed...
Date: Thu, 6 May 1993 16:54:42 +0300

Thank you, Michael.  (I didn't offer this guy any free books, folks.)
I feel that the O'Reilly people working on Linux are part of the
community, and I want us to work together.  Let me explain here the
difference between the collaboration I'm thinking of and pass-through
documentation.  The important thing is deciding what you want to offer
your readers in the long run.

Dual-channel strategy (quality publishing and online distribution)

    Nifty phrase, eh?  Took me almost 10 seconds to think up.

    In this strategy, which is what I suggest for us, I'm not
    promising to publish any single book, much less setting a policy
    of, "Give us everything when you're ready and we'll pass it
    through."  I have read quickly through the KHG, sysadmin guide,
    and uucp guide now, and I'll have things to say about them in my
    next message (this one is already getting too long).

    Go ahead and stick to online distribution -- or quick printings
    for limited use -- for some kinds of books.  You don't need the
    enormous overhead of professional production, marketing, and so
    forth, for quickly changing material, or stuff used just by
    hackers.  (Some of the KHG is useful for other people besides
    kernel hackers.)  You want the freedom and flexibility to change
    them on a whim and tell people to get them again.

    For more substantial books that need careful pacing and attention
    to detail, you want the full professional treatment.  You want an
    editor telling you when concepts have dropped out, or when you're
    boring people with details that should be in later chapters.  You
    also would benefit from nice graphics and cover design, a focused
    marketing campaign, etc.  If this is sounding to you a lot like an
    O'Reilly book -- then you're absolutely right.  And
    congratulations for knowing so well what we put into our books.

    In short, what's good for the readers is good for you and for the
    publisher.  Publish the major books with strict attention to
    accuracy and long-range value, but use cheap printing or online
    distribution for less formal books that people learn about through
    the grapevine.

Pass-through publishing

    This is the other common approach, which is not limited to
    Prentice Hall, and which you should think about in the abstract
    for a minute.  In this strategy, a publisher says that it will
    publish whatever you give them because your output is assumed to
    be informative.  This is used for conference proceedings all the
    time, for instance, and people are just thankful for what they
    get.

    Prentice Hall is commonly associated with this kind of printing
    because of its System V and OSF doc sets.  Prentice Hall is also a
    very important traditional publisher with excellent books in its
    catalog.  I greatly respect the publisher of K&R, K&P, and
    W. Richard Stevens.  But I disagree with their pass-through
    approach, I'm not going to mince words here.

    The System V doc set historically shows lots of problems -- for
    instance, people expect all UNIX systems to work the same way and
    they don't.  AT&T (later USL) stuck in all sorts of AT&T-specific
    tools and features and you can't tell which ones they are.  The
    doc sets don't contain the kind of good conceptual background
    material you need for an introduction (so people have to buy the
    O'Reilly book just to get started) nor do they have the details of
    how things work on each system (so people are forced back to the
    man pages when the going gets tough).

    OSF offers even more of a cautionary tale.  The products were in
    constant flux, long past the moment they sent their documents to
    Prentice Hall.  The published versions are loaded with
    inaccuracies, things that are no longer true, and things that
    don't work yet (and may never work).

    I'll summarize my objection to pass-through publishing for
    computer books this way: it doesn't really offer the readers
    anything they need.  The publisher and author like to claim that
    people are starved for information, so anything is helpful.  I
    don't think that documents freely mixing correct and incorrect
    information are useful.

    What's useful is the dual strategy I proposed above: taking the
    time to make the book really good when it's of long-term interest,
    and keeping your publishing options as flexible as possible
    through online distribution otherwise.

So let's keep talking -- and see my next mail, specifically about the
three alpha drafts currently in the LDP.

----------------------------------------------------------------------
Andy Oram    O'Reilly & Associates, Inc.                 [email-masked]
             90 Sherman Street, Cambridge, MA 02140     (617) 354-5800
                                                    fax (617) 661-1116
----------------------------------------------------------------------

------------------------------

End of DOC Digest
*****************
-------