Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!clyde.concordia.ca!uunet!tut.cis.ohio-state.edu!zaphod.mps.ohio-state.edu!mips!apple!agate!brahms.berkeley.edu!silverio
From: silverio@brahms.berkeley.edu (C J Silverio)
Newsgroups: comp.sys.mac.programmer
Subject: Re: Ideal Inside Mac...here we go again
Message-ID: <1989Dec23.204847.12030@agate.berkeley.edu>
Date: 23 Dec 89 20:48:47 GMT
References: <37460@apple.Apple.COM>
Sender: usenet@agate.berkeley.edu (USENET Administrator;;;;ZU44)
Reply-To: silverio@brahms.berkeley.edu.UUCP (C J Silverio)
Organization: Bath Department, UC Merkeley
Lines: 114

Mark B. Johnson asks:
>Assuming the assertion above to be true, then what is the ideal
>Inside Mac?

Thanks for taking the time to solicit opinions. Here's mine.

1. The most important change necessary for Inside Mac is that it MUST
be reorganized. 

1a. It's time to move all the hardware chapters into a separate
volume. The same goes for the Human Interface chapters (which actually
should be deleted since the Human Interface book supposedly supersedes
them).

1b. The Programmer's Guide to MultiFinder MUST be made part of the
standard manuals. If nothing else, put it (or PLEASE an up-to-date
version of it) in Inside Mac VI. 

1c. There are too many required sources of information about any given
topic. Virtually every manager has more than 5 separate documents
which must be read, understood, and reconciled to effectively program.

2. Inside Macintosh is also long overdue for a total rewrite.

2a. Delta documents MUST be eliminated. They add months to the
learning curve of new programmers and greatly slow down even
experienced hackers who need to look something up. Each delta document
MUST be folded into a rewritten version of the chapter in question.

2b. Many technotes would be obviated by clearer explanations in a
rewritten Inside Mac, and the rest should be attached to specific
chapters in the form of programming notes (including sample code
fragments) and compatibility notes.

2c. For that matter, many extremely terse sections of Inside Mac need
rewriting. DTS can certainly provide information about which sections
would be the best candidates. 

2d. Better treatement and organization of crucial compatibility
information (color, multifinder, HFS, processor, AND valid versions of
the System software) needs to be built into the chapters of Inside Mac
AND ALSO in separate documents that treat the concepts as a whole.

2e. For that matter, it would be nice if every manager had a couple of
pages of sample code fragments that illustrated simple and advanced
uses of the manager.

3. There are several additional services that Apple could provide to
greatly increase the productivity of programmers, as well as the
compatibility, user interface, and programming style of software.

3a. An updateable form of Inside Mac would make many programmers very
happy. They could be sure that their Inside Mac was current and
correct, and that all of the information they need is in one place.

3a1. A subscription service which provided updated looseleaf pages
would find enough buyers to be fiscally reasonable, especially if one
or more Mac software giants were to buy in. (Example: The M&M Photo
Lab Index costs almost $100, but a year's worth of mothly updates is
about $20.) I would guess that a quarterly-update subscription service
to Inside Mac would basically cost (in materials) a bit less than the
tech note service does now, plus the cost of any new chapters that are
added. I won't guess how many more writers Apple would have to hire.

3b. APDA should publish in its APDALog a chart of all the pieces of
Macintosh documentation, what each piece concerns, and what sorts of
packages can be bought that contain the given pieces. As new documents
are released, they should be added to the chart and highlighted so
that programmers can make sure that they are up-to-date.

3c. Apple should purchase and keep current the Inside Mac DA (or
Programmer's Online Companion), since they are the single biggest
timesavers a programmer can have.

Now, I understand that this plan is an extraordinary amount of work to
implement. Here are some "bottom-line" reasons why Apple should
strongly consider doing so:

1. More software will be produced for Macintosh, more quickly, more
compatibly, and in better accord with the Human Interface guidelines. 

1a. All programmers will become more productive. The very act of
looking something up will be drastically faster.

1b. Novice programmers will be able to get up the enormous learning
curve MUCH faster. Novice programmers each spend weeks collecting,
reading, digesting, and (if they are smart) making crib sheets for the
various managers. Almost all of that time would be eliminated with a
rewritten Inside Mac.

1b1. More programmers will want to learn Mac programming, since it
will be significantly easier.

1c. More programmers will be operating with up-to-date information. It
will be easier for them to stay up-to-date.

1d. Programmers will have more time to improve human interface
features. 

1e. More, better software sells more computers.

2. Many major computer companies have a drastically different approach
to documentation than Apple does. Namely, they keep their
documentation up to date, publishing revised manuals instead of
technotes.

3. It will be easier, in the long run, to maintain documentation than
completely rewrite it every few years.

4. Improved documentation would reduce the load on DTS.

5. It is possible that so many programmers would rather have improved
documentation that they would be willing to help pay for it. Major
software houses certainly would, and smart consultants would.