Path: utzoo!utgpu!water!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!mailrus!ncar!tank!nucsrl!bob
From: bob@eecs.nwu.edu (Bob Hablutzel)
Newsgroups: comp.sys.mac
Subject: Re: Inside Mac
Message-ID: <10330069@eecs.nwu.edu>
Date: 26 Oct 88 12:49:18 GMT
References: <19358@apple.Apple.COM>
Organization: Northwestern U, Evanston IL, USA
Lines: 70

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?

To which Kent Borg replies:

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

Personally, my copy of IM IV has already fallen apart. (Between the 
File Manager and List Manager chapters). Granted, loose-leaves are not
as easy to flip through, but I think it's a small price to pay.

> 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.

Exactly. Loose-leaf IM would be easier to change. That's the whole point.
People's copies would agree, if they kept up with the revisions to the
manual (which should be sent out with the floppies for the new system).
To those who say this will make the system cost, or cost more, I say
"It's worth it".

> 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.

The Macintosh isn't going to stand still because IM is nicely bound.
If it did, we wouldn't have IM IV and IM V. Look at the history. The 
Macintosh is moving, it isn't going to stop moving, and IM is static.
Thus IM is moving more and more out of phase with the Macintosh, 
making things like Tech Notes, and new volumes of IM, a neccessity.

The binding force in the Macintosh is the installed software, not the
installed documentation. Get a clue.

> 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.

Exactly right. But it's senseless to update the whole damn manual, when
you just update the relevent chapters. Do you want ROM patches to replace
the whole ROM, rather than just tiny parts of it? And personally, I'd
much rather update a few pages in a loose leaf manual than remember that
there was a Tech Note on the subject.

> 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.

Right. The anchor on the changes to the Macintosh is the installed software,
not the documentation. The real cost of the unupdatable documentation is in
the poor novice programmer, learning all about the file manager from IM II,
for example, only to read a little further on and realize that this information
is meaningless. Same goes for Quickdraw in IM I, vs. Quickdraw in IM V.
The real cost is in having to figure out which part of the documenation is
real, and which part is replaces, and which part is in a Tech Note.  For
this, there is no excuse.

Oh, well. Guess we don't agree on this subject. :-) 


Bob Hablutzel		BOB@NUACC.ACNS.NWU.EDU