Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!wuarchive!cs.utexas.edu!tut.cis.ohio-state.edu!bloom-beacon!bu-cs!dartvax!eleazar.dartmouth.edu!ari
From: ari@eleazar.dartmouth.edu (Ari Halberstadt)
Newsgroups: comp.sys.mac.programmer
Subject: Re: Better Docs/more proposals/useful sources of info
Message-ID: <16467@dartvax.Dartmouth.EDU>
Date: 2 Nov 89 11:44:06 GMT
References: <1989Nov1.232424.8861@agate.berkeley.edu>
Sender: news@dartvax.Dartmouth.EDU
Reply-To: ari@eleazar.dartmouth.edu (Ari Halberstadt)
Organization: Dartmouth College, Hanover, NH
Lines: 84

In article <1989Nov1.232424.8861@agate.berkeley.edu> silverio@brahms.berkeley.edu (C J Silverio) writes:
>I am sick to death of trying to code Mac applications with the
>existing documentation.
>
>Consider, for example, the case of TextEdit. It was originally
>documented in IM-I, then there were a few tech notes on it, then it
>was revised in IM-IV and again in IM-V, with a spate of additional
>tech notes following. One needs to obtain, read, and piece together
>all of these bits of info to use TextEdit with maximum effect. Why
>hasn't anybody done this piecing together already?
>
>What I want is a set of three-ring binders that contains one chapter
>per manager. Whenever Apple adds more documentation affecting that
>manager (a tech note, a new IM chapter, etc.), I want a revised
>version of the entire chapter, as well as a short, succinct
>notification of what changed. (I won't ask for "change bars" since
>everyone knows they were invented by IBM.)

Yes yes...the project I've been working on
took me 1/4 times longer cause of lousy docs. At least Apple
cleaned up their mess in AU/X...they have about 20 manuals, ring
bound, small, and the binder rings are ROUND!!! Yes, you don't have
to push 600 pagesto get to the index!!! (or maybe I'm fantasizing,
maybe in fact the binder rings are rectangular...). Each manual
actually deals with what it says: there's one about text editing,
one about games (ya, they put rogue on the mac :-), etc.

BTW, who on earth invented square binder rings with 500 page
manuals? He/she should be left out to dry in the Sahara desert!
And, to keep this evil person company, we should send the people
who have been maintaining Apple documentation (I like the first three
manuals, we'll be nice to the original team).

>(Of course, if this information was to also be available as an
>updateable, monster Hypercard stack, I wouldn't complain, but frankly,
>I can read printed pages much more easily than computer monitors, so
>I'd also insist on paper copies.)

It is, but only the tech notes. Besides, I can't run Hypercard and
my debugger and program at same time, even on 4 and 5 meg machines...

The best things to date:
	1. Inside Mac DA. The version I have goes up to vol IV, which
	is most of what you need. Saves endless trips to the bookshelf.
	It's amazing how 4 volumes can be shrunk to 6x5 inches.

	2. OnBase. When you need a prototype, or the name of a field
	in some obscure structure, OnBase is the one!

	3. HyperCard technotes stack. Just the regular tech's, but in
	stack form.

	4. MAC DTS sample code. Virtually useless to me, since I've had
	to learn all that junk myself...oh well. The examples just aren't
	terribly serious. And even on Phil and Dave's excellent CD I
	could find no sample DA code, so again I had to plow through
	three very poorly documented sections of IM. Turned out, writing
	a DA is simpler than an application, once you know how.

Maybe we could have a frequently asked questions posting,
a sample code posting, a "where to get help" and "you're not alone"
posting, etc. Seems nearly everyone (including myself) starts out with just
about the same problems, asks the same questions, breaks their heads
on the same problems...what's the point??? We just need to find someone
who will be willing to repost every, 2-3 weeks, and who will take submissions
and include them (if deemed worthy or demanded by the net). If possible,
people could help him/her out by sending copies of things that appeared
on the net, just in case they were missed by our volunteer (keep this
last idea to a minimum, don't want to swamp the mailer).

That's about it. Oh, someone asked about handles, but I couldn't
get through to him. If you're still out there:
	**hndl = SomethingThatFoolsWithMemory();
Don't do that: THINK C evaluates the pointer first, then calls the
function, so if memory moves, you're in trouble. Similarly, don't do
	SomethingThatFoolsWithMemory(&(**struct_hndl).element);
For the same reason.


--

-- Ari Halberstadt '91, "Long live succinct signatures"
E-mail: ari@eleazar.dartmouth.edu
Disclaimer: "Live Free or Die"