day@grand.UUCP (Dave Yost) (05/14/89)
Imagine...
It's 1990. A programmer, perhaps already expert in
another type of system, finally gets the message that
the Mac is great, and wants to learn how to program it.
Scenario 1:
He (or she) goes out and buys the Technical
Introduction, the Software Introduction, the Hunan
Interface Guidelines, the Multifinder Notes volumes
1 - 3, Inside Mac volumes I - VII, all 473 Tech
Notes, the MacApp documentation and sources, and
"Tips from Apple insiders on the Net" (5,344
pages). While struggling through this material, he
watches the net to look for bits of wisdom, finds
brisk traffic about all sorts of tricky problems.
Five months later he takes a job as a farm hand.
Scenario 2:
He goes out and buys The Macintosh Technical
Documentation, Version 7.0 (10 volumes). These
books have revision bars in the margin for the
benefit of old-timers, but he ignores them. He
reads the tutorial in the first few volumes, feels
like he has a clear and consistent view of mac
software, then he proceeds to produce good code,
occasionally referring to the reference material in
the remaining volumes, and to the 200-page, totally
complete two-level Index.
We can wish.
--davekeith@Apple.COM (Keith Rollin) (05/14/89)
In article <496@grand.UUCP> day@grand.UUCP (Dave Yost) writes: >Imagine... > >It's 1990. A programmer, perhaps already expert in >another type of system, finally gets the message that >the Mac is great, and wants to learn how to program it. > >Scenario 1: > > [ The state of today ] > >Scenario 2: > > [ The vision of tomorrow ] > >We can wish. > I can see how this topic can easily explode into another session on Apple bashing ("Why the Hell can't Apple get its act together and put out some decent documentation?"), so I just wanted to let people know what was currently going on. By now, you all should have heard about the features of 7.0. Mark Johnson posted the summaries to the net, and there has been some discussion on various topics already. As you can see, there is a *LOT* going on. Even the media has hardly failed to notice the significance of what we are doing. Practically EVERYONE in Technical Publications is working on the documentation for 7.0 right now. Other projects already started have been put on hold in order so that we may have the documentation done at the same time as the software. People at the Developer's Conference received binders full of preliminary documentation, but there is still lots to do. Until then, there is very little we can do to combine everything into one place. Besides, I'm sure that everyone here would like to see the Combined Technical Works of the Macintosh include System 7.0 stuff, so we need to get it done first anyway. At the very least, there the job security of people like me to consider, who get paid for know what's in these manuals... :-) ------------------------------------------------------------------------------ Keith Rollin --- Apple Computer, Inc. --- Developer Technical Support INTERNET: keith@apple.com UUCP: {decwrl, hoptoad, nsc, sun, amdahl}!apple!keith "Argue for your Apple, and sure enough, it's yours" - Keith Rollin, Contusions
day@grand.UUCP (Dave Yost) (05/16/89)
In article <30650@apple.Apple.COM> keith@Apple.COM (Keith Rollin) writes: > Practically EVERYONE in Technical Publications is working on the > documentation for 7.0 right now. Other projects already started have been > put on hold in order so that we may have the documentation done at the same > time as the software. Until then, there is very little we can do to > combine everything into one place. Besides, I'm sure that everyone here > would like to see the Combined Technical Works of the Macintosh include > System 7.0 stuff, so we need to get it done first anyway. So there's hope then, that the Mac technical documentation may someday be consolidated? It would be so much better to have a consistent, periodically revised and expanded complete work than a base work with deltas. --dave yost
werner@molokai.sw.mcc.com (Werner Uhrig) (05/17/89)
In article <496@grand.UUCP>, day@grand.UUCP (Dave Yost) writes: > Imagine... > > It's 1990. A programmer, perhaps already expert in > another type of system, finally gets the message that > the Mac is great, and wants to learn how to program it. > > Scenario 1: ....I couldn't think of a humourous remark to this sad description of the state of affairs ... > Scenario 2: > > He goes out and buys The Macintosh Technical > Documentation, Version 7.0 (10 volumes). These > books have revision bars in the margin for the > benefit of old-timers, but he ignores them. He > reads the tutorial in the first few volumes, feels > like he has a clear and consistent view of mac > software, then he proceeds to produce good code, > occasionally referring to the reference material in > the remaining volumes, and to the 200-page, totally > complete two-level Index. hehe, I've said since 1984 that Apple missed out on learning one thing from Big Blue: how to write documentation that can be supported over the years; I still say the same thing. I only had to grin when I thought of the commercial Big Blue could launch, IFF they'd ever get down to mentioning the competition: Remember the 1984ish Apple TV-ad with showing the itty-bitty Macintosh-documentation "butterflying" down on the table ? "that's all you need on the Macintosh" ... ...followed by the 1990-reality *CLUNK* of the 10 volumes; welcome to the "real world", kid. wait until you get promoted to the second grade where we'll talk of "virtual memory", "version-control", "automatic job-scheduling", "macro-languages", "generation-file-names", "source-code control", ... well, at least marketing behaves like IBM-clones already ... <wink-wink, nudge-nudge... what, that tear in my eye? just a little onion ...> -- --------------------------> please send REPLIES to <------------------------ INTERNET: uhrig@mcc.com (if unavailable: werner@rascal.ics.utexas.edu) UUCP: ...<well-connected-site>!milano!werner ALTERNATIVE: werner@astro.as.utexas.edu OR werner@utastro.UUCP