mjohnson@Apple.COM (Mark B. Johnson) (12/21/89)
In article <8576@ttidca.TTI.COM> schear@ttidca.tti.com (Steve Schear) writes: >I would guess that with System 7.0 just around the corner, Apple will >wait till its release to update IM. I almost hate to start this again, because last year I had over 45+ pages of comments... Assuming the assertion above to be true, then what is the ideal Inside Mac? Is it bound? 3-ring punched and updatable? Both? Neither? Is it organized according to task? Manager? Alphabetically? Does it include Pascal AND C interfaces? How much assembly-language information? Is it a reference manual? A tutorial? Both? Neither? I think you get the idea. What's nirvana? If you have an AppleLink account, you can send these comments and more directly to the Developer Technical Publications group in the Developer Services board through the Tech Pubs two-way discussion folder. If not, send them to me (why am I getting myself into this again) or post them and I'll collect them to pass along. -- Mark B. Johnson AppleLink: mjohnson Developer Technical Support domain: mjohnson@Apple.com Apple Computer, Inc. UUCP: {amdahl,decwrl,sun,unisoft}!apple!mjohnson "You gave your life to become the person you are right now. Was it worth it?" - Richard Bach, _One_
oster@dewey.soe.berkeley.edu (David Phillip Oster) (12/22/89)
In article <37460@apple.Apple.COM> mjohnson@Apple.COM (Mark B. Johnson) writes: >What is the ideal Inside Mac? Is it bound? 3-ring punched and updatable? Has anyone tried out the new SpInside Mac that was included on the Release Version of Phil & Dave's CD? My copy just arrived today, but since I don't personally own a CD drive... --- David Phillip Oster -- No, I come from Boston. I just work Arpa: oster@dewey.soe.berkeley.edu -- in cyberspace. Uucp: {uwvax,decvax}!ucbvax!oster%dewey.soe.berkeley.edu
beard@ux1.lbl.gov (Patrick C Beard) (12/23/89)
In article <33360@ucbvax.BERKELEY.EDU> oster@dewey.soe.berkeley.edu.UUCP writes: >Has anyone tried out the new SpInside Mac that was included on the Release >Version of Phil & Dave's CD? My copy just arrived today, but since I >don't personally own a CD drive... Yes. SpInside Mac is great. They have it cross-referenced with the Tech Notes stack, and the chapters are all in order (Quickdraw is followed by Color QuickDraw, etc.). The size of the thing is a little too expensive for my hard disk (~14 MB) so I guess it will have to stay on the CD. Now, the next logical step is for Apple to purge all tech notes, add the information to the real chapters, and start over with the tech note number series. The real examples and data has been in the tech notes the last few years. We need to put it in the main publication itself. Just speaking my and my co-worker's minds. ------------------------------------------------------------------------------- - Patrick Beard, Macintosh Programmer (beard@lbl.gov) - - Berkeley Systems, Inc. ".......<dead air>.......Good day!" - Paul Harvey - -------------------------------------------------------------------------------
paul@taniwha.UUCP (Paul Campbell) (12/23/89)
In article <33360@ucbvax.BERKELEY.EDU> oster@dewey.soe.berkeley.edu.UUCP (David Phillip Oster) writes: >Has anyone tried out the new SpInside Mac that was included on the Release >Version of Phil & Dave's CD? My copy just arrived today, but since I >don't personally own a CD drive... It's on par with the technotes stack - you can access by subject or index I haven't used it much yet but I have one major problem - I can't play my music while I use it :-) and don't have enough space to put it online all the time - which may make it easier or less disruptive to look up the hard copy rather than load up the disk (you would have thought that the user interface people would have thought of this wouldn't you :-) Paul -- Paul Campbell UUCP: ..!mtxinu!taniwha!paul AppleLink: CAMPBELL.P "We got a thousand points of light for the homeless man, Got a kinder, gentler, machine gun hand ..." - Neil Young 'Freedom'
wdh@well.UUCP (Bill Hofmann) (12/24/89)
In article <33360@ucbvax.BERKELEY.EDU> oster@dewey.soe.berkeley.edu.UUCP (David Phillip Oster) writes: >In article <37460@apple.Apple.COM> mjohnson@Apple.COM (Mark B. Johnson) writes: >>What is the ideal Inside Mac? Is it bound? 3-ring punched and updatable? > >Has anyone tried out the new SpInside Mac that was included on the Release >Version of Phil & Dave's CD? My copy just arrived today, but since I >don't personally own a CD drive... It's real nice, and cross-ref'd with the Q&A Stack and the Tech Note Stack, like it should be. However, it's STILL in Hypercard, so, it's rather mind- deadeningly slow. And of course, just try and check the usage of a trap from Macsbug... So I guess the cost of SpInside Mac is the disk plus a CD drive plus a spare mac. Based on my usage of Inside Mac, what I could use is a sort of hierarchical Inside Mac: maybe a nice spiral bound quick reference (traps and etc alphabetically, like Programmer's Online Companion) with pointers into a larger set of documentation, including sample code fragments with a STANDARD coding style, and painfully clearly documented. Because there are plenty of times that computerized documentation isn't the best thing (like, you can't afford to dedicate a Mac to be Inside Mac), it's important that the printed documentation has some thought put into it. But the computerized stuff is invaluable, especially the part about the penguins. -Bill Hofmann
silverio@brahms.berkeley.edu (C J Silverio) (12/24/89)
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.
6500stom@hub.UUCP (12/24/89)
>>In article <37460@apple.Apple.COM> mjohnson@Apple.COM (Mark B. Johnson) writes: >>>What is the ideal Inside Mac? Is it bound? 3-ring punched and updatable? For what its worth, however you put together the new IM manuals you need to add tabs on the side of the pages to indicate the start of chapters. Right now I'm using a bunch of post-it notes to get the same effect. You can just flip to the manager you want really easily. / Josh Pritikin T Ignorance is bliss. \ | Internet: 6500stom@ucsbuxa.ucsb.edu | I must be in hell. | | AppleLink: Josh.P | My room is proof that entropi | \ GEnie: J.Pritikin ! exists. /
d6maca@dtek.chalmers.se. (Martin Carlberg) (12/28/89)
In article <1989Dec23.204847.12030@agate.berkeley.edu> silverio@brahms.berkeley.edu.UUCP (C J Silverio) writes: >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. [Lots of good stuff deleted] ... >documentation that they would be willing to help pay for it. Major >software houses certainly would, and smart consultants would. I think C J Silverio is talking sense. Go for it Apple! - Martin Carlberg - Chalmers University of Technology, Gothenburg, Sweden
pollock@ziggy.EDU (Wayne Pollock) (12/29/89)
In article <1989Dec23.204847.12030@agate.berkeley.edu> silverio@brahms.berkeley.edu.UUCP (C J Silverio) writes: >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. > ... [Many teriffic suggestions deleted] Bravo to C J Silverio! I've wanted to tell all that to Apple for some time. And Apple, least you think it isn't feasible to do all that, especially the regular updates to keep IM current, go talk to you lawyer; I'd bet he has several update-able informations sources. If it works for other professions, it ought to work for computer programmers too! Wayne Pollock (The MAD Scientist) pollock@ziggy.usf.edu Usenet: ...!{gatech!uflorida!}ziggy!pollock GEnie: W.POLLOCK