Xref: utzoo comp.sys.mac.programmer:2927 comp.sys.mac:22117 Path: utzoo!utgpu!water!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!cwjcc!hal!nic.MR.NET!shamash!nis!com50!pai!erc From: erc@pai.UUCP (Eric Johnson) Newsgroups: comp.sys.mac.programmer,comp.sys.mac Subject: Re: Inside Mac Summary: An electronic distribution would be helpful Message-ID: <250@pai.UUCP> Date: 27 Oct 88 15:11:54 GMT References: <19358@apple.Apple.COM> <234@lloyd.camex.uucp> <19510@apple.Apple.COM> Organization: Prime Automation, Inc., Burnsville, MN Lines: 191 In article <19510@apple.Apple.COM>, mjohnson@Apple.COM (Mark Johnson) writes: > In article <234@lloyd.camex.uucp> kent@lloyd.UUCP (Kent Borg) writes: > >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? > >... > >Don't do it. A book is much tougher, loose-leaves are always loose. > > > >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. > > > >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. > > > >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. > > > > Currently many versions of IM exist in the world so there is already the > problem of inconsistent information (how many people are still using > phone books?). In addition, the numerous volumes of IM along with Tech > Notes and third-party documentation make looking up a simple call an > experience in itself (which sometimes takes longer than the trial-and-error > method). > > Does this mean that Apple should just maintain the status quo until that > time that we see fit to rewrite IM? Obviously, if we were to do a complete > rewrite of IM it would be an opportune time to change formats, but what if > the rewrite does not come? Then what? > > If IM were rewritten and could be condensed into one (or two) volumes, > would that solve the problems or is the real question here still the > ability for us to distribute and you to receive REVISABLE documentation? > Personally, I just don't consider multiple hardbound volumes very revisable. > > Mark Johnson > Developer Technical Support > Apple Computer, Inc. Just my $0.02... What I would like, ideally, is one source for all "official" Macintosh programmers' documentation, e.g., Tech Notes, Inside Macintosh, Programmer's Introduction to the Macintosh, Inside AppleTalk, SANE, et al. I would like that one source to include both text and graphics (a good picture is really handy sometimes). I would like that one source to be extensively cross-referenced, so I could easily find all the "official" information on a given topic. I would like that one source to be in BOTH paper (hard copy) and electronic formats. I find I prefer to READ a book (loose-leaf or not), but the electronic format allows me to quickly search for items, and easily jump to cross-reference links. In any format, I would rather not have to buy new manuals when the information is updated (as we all know it will be). I don't mind purchasing update pages, but having to buy a new version of the same manual is galling. So, I guess I am asking for some form of HyperText (not necessarily HyperCard) format for an electronic be-all end-all manual set. It would ideally include: * Extensive cross-reference links, to allow me to "jump" to other sections of the manual that are relevant to the topic at hand. * Many more code examples. I would like to see both C and Pascal (Pascal is not the only high-level language for the Mac anymore). Complete, WORKING programs would be very useful to help illustrate various topics (I know this would take a lot of time to develop). * Integrated text and graphics. Again, graphics are very useful for conveying certain types of information. * Sections listing known problems (by System/Finder version numbers) with various system calls and software managers. Any large software system has bugs. It would be nice to have known bugs explicitly identified (it would certainly help development efforts). If a bug existed in a certain system release and was later fixed, this section should say so. * An ability to print out (on a LaserWriter or ImageWriter) any parts (including all) of the electronic manual. (E.g., if the paper edition was not handy, or if I wanted to print out cross- referenced pages together, when in the paper edition these sections were in different volumes.) * Ability for me to include my own comments in various sections of the manual. These comments should be available to be read and printed, but NOT considered part of the manual, so that the manual could be updated (see below) and my comments would not be wiped out. * Easily updated when new versions or sections came out from Apple. The ease of updating would encourage developers to get the latest goodies. I fully realize that this would be a BIG BIG BIG task to create. It is also more than any other computer manufacturer offers in terms of technical documentation (I believe). But, I feel the Macintosh is a special machine, and needs more extensive documentation. Some observations: * The Macintosh interface makes the Mac harder to program than many other computers, especially those by the Irish Business Machines company. Event-driven programming is new to many people coming from more traditional computer backgrounds. Apple needs extensive, quality documentation (this is NOT a flame on the current status quo) to help developers write quality applications. * When Apple updates the Mac operating system, a number of applications that USED to run always seem to bomb under the new system. I don't care whose fault it is -- the fingers point at Apple. The blame lands at Apple, EVEN IF APPLE IS NOT AT FAULT. This makes Apple look bad. Therefore, if Apple wants developers to write applications that WON'T BOMB on new system updates, it is in Apple's interest to help developers follow the rules (again, I am making observations and NOT flaming any current practices). Sometimes, the rules change. It is in Apple's interest to help developers keep up-to-date on the rules. It is also in Apple's interest to help developers learn about the rules in the first place. * The more software that is available for the Mac means that more Macs will be sold. The more Macs sold means that more software gets sold and that there is a bigger market for certain types of software. I am sure all major computer manufacturers are aware of this symbiotic relationship between developers and manufacturers. It is in Apple's interest to help developers create more Mac software, because this will help sell more Macs. Therefore, it is in Apple's interest to * make it easier to write Macintosh software, * make it easier to write Mac software that will still run across system updates, and * make it easier for non-Mac or new developers to start developing on the Mac. Programming Documentation can help meet those above goals. I think it is in Apple's interest to improve its programming documentation to better meet those goals. I am not trying to complain about the status quo. I am trying to make constructive suggestions. I assume Apple knows it can improve (there is ALWAYS room for improvement no matter how well it is done now). I assume Apple wants to improve its documentation (hence the first posting from an Apple person -- and yes, I assume that person made the standard disclaimers). Finally, I think that because the Mac documentation is spread over various divers sources, because the system is changing (every six months or so we have a new system release), because Apple wants developers to create more and better software, it is in Apple's interest to: * collect all Mac programming documentation together * provide more examples * list know problems * list planned changes, so that developers become aware of this I believe a HyperText-style system would help meet those goals and be much easier to use than the current system of looking in IM I-V, Tech Notes, et al., to find information on a given subject. As an exercise for the reader, look in an APDA catalog and list every source of "official" programming information you can find, including AppleTalk, MultiFinder, and so on. I think this shows the need to collect the information together into one source. I think that one source would be very large (given the amount of currently available documentation). I think an electronic-based system for search and retrieval would be necessary to find information in such a body of documentation. Anyway, these are my opinions, take them or leave them. I don't care if you disagree with me (that's life), but before you flame, please remember that my intentons have been to not complain about any current Apple documentation/support activities, but instead to offer suggestions to improve future documentation/support activities. I believe that Apple has many dedicated people who aim at helping Macintosh developers. I would like to thank them. I would also like to thank all Apple staffers who take the time to read the net and respond in many newsgroups, including * comp.sys.mac.programmer * comp.sys.mac * comp.sys.mac.hypercard * comp.unix.aux * and so on Have fun, -Eric -- Eric F. Johnson | Phone +1 612-894-0313 | Are we Prime Automation,Inc | UUCP: bungia!pai!erc | having 12201 Wood Lake Drive | UUCP: sun!tundra!pai!erc | fun Burnsville, MN 55337 USA | DOMAIN: erc@pai.mn.org | yet?