Xref: utzoo comp.sys.mac.programmer:2905 comp.sys.mac:22036
Path: utzoo!utgpu!water!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!ukma!nrl-cmf!ames!husc6!lloyd!kent
From: kent@lloyd.camex.uucp (Kent Borg)
Newsgroups: comp.sys.mac.programmer,comp.sys.mac
Subject: Re: Inside Mac
Summary: Keep Inside Macintosh a book
Message-ID: <234@lloyd.camex.uucp>
Date: 25 Oct 88 14:20:30 GMT
References: <19358@apple.Apple.COM>
Reply-To: kent@lloyd.UUCP (Kent Borg)
Organization: Camex, Inc., Boston, Mass USA
Lines: 47

In article <19358@apple.Apple.COM> mjohnson@Apple.COM (Mark Johnson) writes:
>                     ... how would you feel about Apple publishing _Inside
>Macintosh_ (and maybe other technical manuals) in loose-leaf or some other
>form which would lend itself to revision without new "delta" editions?
...
>Mark B. Johnson
>Developer Technical Support
>Apple Computer, Inc.
>domain: mjohnson@Apple.com
>UUCP:   {amdahl,decwrl,sun,voder}!apple!mjohnson

Don't do it.  A book is much tougher, loose-leaves are always loose.

The only reason for publishing Inside Macintosh in loose-leaf form
would be to make it easier to change.  If that happens it'll just keep
changing.  If you think system software revisions are confusing in
their numbering, just think if pages all had revisions, pages die,
pages are born.  Hardly anybody's copies would agree.

Apple is always tempted to make changes.  I want Apple to think _very_
carefully before they do.  If we think the rules are a moving target
now, have fun if the principal constraint on their motion--Inside
Macintosh--starts spinning.

Sure, there will always be a need for update information, and for
smallish deltas the Technical Notes should be used.  For larger
deltas, a new volume of Inside Macintosh can be published.  For those
_really_ big changes (System update 7.0?  8.0?) Inside Macintosh
should be rewritten.

Moral: Don't get confused about the cost of changing documentation.
The cost of changing Inside Macintosh is _not_ the the cost of all the
bound books, it is the cost of the established software written under
that old documentation, it is the innumerable hours spent learning
what is in that old documentation.

Having a bunch of bound books out there on which you cannot do a
search and replace is a good reminder of the enormous cost of changes.

Changes should be made, the Macintosh has problems that need fixing,
but it should be done _very_ carefully.  The system is at risk for
being badly muddled right now.  Be careful.

Kent Borg
kent@lloyd.uucp
or
hscfvax!lloyd!kent