mjohnson@Apple.COM (Mark Johnson) (10/24/88)
Thanks to all of you who have sent me your comments concerning Tech Notes.
Keep them coming as long as you have them. Since it was mentioned by a few
people in their responses, 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?
Any and all suggestions and comments should be addressed to me below. Thanks
for your time.
Mark B. Johnson
Developer Technical Support
Apple Computer, Inc.
domain: mjohnson@Apple.com
UUCP: {amdahl,decwrl,sun,voder}!apple!mjohnsonkent@lloyd.camex.uucp (Kent Borg) (10/25/88)
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? ... >Mark B. Johnson >Developer Technical Support >Apple Computer, Inc. >domain: mjohnson@Apple.com >UUCP: {amdahl,decwrl,sun,voder}!apple!mjohnson 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. Moral: Don't get confused about the cost of changing documentation. The cost of changing Inside Macintosh is _not_ the the cost of all the bound books, it is the cost of the established software written under that old documentation, it is the innumerable hours spent learning what is in that old documentation. Having a bunch of bound books out there on which you cannot do a search and replace is a good reminder of the enormous cost of changes. Changes should be made, the Macintosh has problems that need fixing, but it should be done _very_ carefully. The system is at risk for being badly muddled right now. Be careful. Kent Borg kent@lloyd.uucp or hscfvax!lloyd!kent
alexis@ccnysci.UUCP (Alexis Rosen) (10/26/88)
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? DO IT!!! Tech notes are a nice way to 'fix' Inside Mac, but it would be nicer if we could just insert new sections. Speaking of IM, when is the fabled re-write coming? ---- Alexis Rosen alexis@dasys1.UUCP or alexis@ccnysci.UUCP Writing from {allegra,philabs,cmcl2}!phri\ The Big Electric Cat uunet!dasys1!alexis Public UNIX {portal,well,sun}!hoptoad/
bob@eecs.nwu.edu (Bob Hablutzel) (10/26/88)
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? To which Kent Borg replies: > Don't do it. A book is much tougher, loose-leaves are always loose. Personally, my copy of IM IV has already fallen apart. (Between the File Manager and List Manager chapters). Granted, loose-leaves are not as easy to flip through, but I think it's a small price to pay. > 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. Exactly. Loose-leaf IM would be easier to change. That's the whole point. People's copies would agree, if they kept up with the revisions to the manual (which should be sent out with the floppies for the new system). To those who say this will make the system cost, or cost more, I say "It's worth it". > 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. The Macintosh isn't going to stand still because IM is nicely bound. If it did, we wouldn't have IM IV and IM V. Look at the history. The Macintosh is moving, it isn't going to stop moving, and IM is static. Thus IM is moving more and more out of phase with the Macintosh, making things like Tech Notes, and new volumes of IM, a neccessity. The binding force in the Macintosh is the installed software, not the installed documentation. Get a clue. > 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. Exactly right. But it's senseless to update the whole damn manual, when you just update the relevent chapters. Do you want ROM patches to replace the whole ROM, rather than just tiny parts of it? And personally, I'd much rather update a few pages in a loose leaf manual than remember that there was a Tech Note on the subject. > Moral: Don't get confused about the cost of changing documentation. > The cost of changing Inside Macintosh is _not_ the the cost of all the > bound books, it is the cost of the established software written under > that old documentation, it is the innumerable hours spent learning > what is in that old documentation. Right. The anchor on the changes to the Macintosh is the installed software, not the documentation. The real cost of the unupdatable documentation is in the poor novice programmer, learning all about the file manager from IM II, for example, only to read a little further on and realize that this information is meaningless. Same goes for Quickdraw in IM I, vs. Quickdraw in IM V. The real cost is in having to figure out which part of the documenation is real, and which part is replaces, and which part is in a Tech Note. For this, there is no excuse. Oh, well. Guess we don't agree on this subject. :-) Bob Hablutzel BOB@NUACC.ACNS.NWU.EDU
werner@utastro.UUCP (Werner Uhrig) (10/26/88)
In article <234@lloyd.camex.uucp>, kent@lloyd.camex.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? < ... < >Mark B. Johnson < >Developer Technical Support < >Apple Computer, Inc. > > 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 I should have been done loos-leaf to start, and it is not too late to do it *RIGHT* ... I repeat what I said in 1984: Manuals is one thing you should learn from IBM ... -- --------------------> PREFERED-RETURN-ADDRESS-FOLLOWS <--------------------- (ARPA) werner@rascal.ics.utexas.edu (Internet: 128.83.144.1) (INTERNET) werner%rascal.ics.utexas.edu@cs.utexas.edu (UUCP) ..!utastro!werner or ..!uunet!rascal.ics.utexas.edu!werner
mjohnson@Apple.COM (Mark Johnson) (10/26/88)
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.
lippin@jell-o.berkeley.edu (The Apathist) (10/27/88)
>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? I'm ready for the change. I'm sick of having to scrounge through all the documentation before I can discover truth in `the book of Macintosh.' Another advantage of the loose-leaf form is that it would be possible to publish new chapters individually. From reading IM V, it seems clear that some chapters just weren't ready to go to the printer when the deadline hit. They could have been published later, or published as draft versions and rewritten if it was a loose-leaf. On the other hand, none of this will work if Apple isn't willing to properly keep up the loose-leaf manuals. This means that when there's a revision, they need to print replacement pages, not just a set of deltas, which would be less expensive. Recently kent@lloyd.UUCP (Kent Borg) wrote: >Don't do it. A book is much tougher, loose-leaves are always loose. This looks to me like the biggest problem with loose-leaves. But I've seen a few UNIX manuals that could stand up to heavy use, so I think this can be done right. Just keep robustness in mind when designing the manuals. Use reinforced cover pages, roomy binders, and heavy paper. >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. On the other hand, people's IM's all agree now (assuming they're up to volume V), but, often enough, they're all wrong. And even when they're not, you have to consider that what's in one volume is sometimes contradicted by what's in another, or by a tech note. And keeping your knowledge of the tech notes up to date is certainly no easier than keeping a loose-leaf binder up to date. I don't think that making the manuals hard to change is going to keep the system from changing -- it's the existing applications that do that. And, IMHO, Apple is already bending over backward to keep some programs alive that deserve to die. --Tom Lippincott ..ucbvax!math!lippin "This view derives partly from what is known as common sense, whose virtue, uniquely among virtues, is that everyone has it." --Tom Stoppard, "Jumpers"
gsbrob1@apcvxa.uchicago.edu (10/27/88)
>In article <234@lloyd.camex.uucp>, kent@lloyd.camex.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. > > > I should have been done loos-leaf to start, and it is not too late > to do it *RIGHT* ... I repeat what I said in 1984: Manuals is one > thing you should learn from IBM ... I think both sides have good arguments. I think that a looseleaf edition would indeed be more useful though, since outdated information wouldn't sit around for so long. But the books would tend to hold up better over the long run, and they do look slicker on bookstores' shelves.:-> Why not do both? Have A-W publish the books, and distribute Inside Mac Binders (and perhaps quarterly updates) through APDA. Or is that making the whole thing too complicated? I guess if I had to choose one over the other, I'd go for binders. Robert gsbrob1@apcvxa.uchicago.edu ra_robert@gsbacd.uchicago.edu ................................................................... . disclaimer: all opinions here expressed are mine and mine alone . ...................................................................
drc@claris.com (Dennis Cohen) (10/27/88)
To further Bob H.'s argument: How about the corrections for the number of outright errors in IM V? Proof- reading doesn't catch everything, especially when you're documenting a moving target like Color QD or Styled TE (just starting to settle down now). People like us want the documentation available as soon as we can get our hands on the hardware. I would much rather have access to the 99% correct information such as IM V, knowing that when the errors that are going to slip through the cracks get caught, I can find out about them and get replacement pages to put in my reference manual. My opinion of loose-leaf vs. perfect-bound is that for something like IM that I want to keep open next to me while I'm working dictates loose-leaf. I can't keep IM IV or V open to the pages I want while I'm at the keyboard unless I either weight the pages down or break the spine -- those are not good solutions. Dennis Cohen Claris Corp. ------------ Disclaimer: Any opinions expressed above are _MINE_! (and there are a lot of them today)
erc@pai.UUCP (Eric Johnson) (10/27/88)
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?
dmcintee@netxcom.UUCP (Dave McIntee) (10/27/88)
The arguments seen in this forum in favor of a loose-leaf format, and those in favor of a bound edition are both valid, so Apple must decide carefully. As a proprietary operating system, unlike Unix, the Macintosh OS is free to evolve as Apple sees fit. They alone determine its future course, for better or worse. While the system is very usable today, there is sure to be a steady improvement in the years ahead. The issue is how to best manage the dissemination of information regarding 1) changes to the OS, and 2) the complete current documentation set at any given moment. These two objectives should be as economical and as useful to both Apple and the development community as possible. Considering all this, I feel that the approach taken by other vendors of proprietary systems would be best for Apple: That is, a loose-leaf documentation set which can be updated as needed, with the updates provided from one source, probably Apply Computer, on an annual subscription basis. This is provided the update subscription fee is reasonable, say in the $25-50 per annum range, so the individual hobbiest will not be squeezed out. Developers who choose to purchase the documentation set but not subscribe to the annual subscription service, can of course do so, and should be able to, at any future time, obtain an update set to bring them up to date. The cost of this should be somewhere between the annual rate and the wholesale price for the entire document. This will protect their investment without forcing participation in the annual service. With this approach, the system can evolve as quickly as appropriate, and everyone's documentation will be current and consistant. As for Tech Notes, perhaps they go away, but that's another matter. -- Dave McIntee NetExpress Communications, Inc. Phone: (703)749-2380 1953 Gallows Road, Suite 300 uunet!netxcom!dmcintee Vienna, VA 22180
mnkonar@pavo.SRC.Honeywell.COM (Murat N. Konar) (10/28/88)
How about making each chapter a separate pamphlet style thingie? Then you'd only have to replace the particular chapter affected. If the pamphlet is drilled for three holed binders it would even be greater. You could pull out only the chapters you need at the moment and not have to worry about breaking the binding of a book style version. Seems to me however that Adison-Wesley wouldn't like such an arrangement for various reasons and therefore I don't really expect a change in format to occur. ______________________________________________________________________ Have a day. :^| Murat N. Konar mnkonar@ely.UUCP Honeywell Systems & Research Center, Camden, MN
mkg@lzsc.ATT.COM (Marsh Gosnell) (10/28/88)
I'd love to see a loose-leaf version (I was that way in the early days). I really dislike having information about a trap in two or more different volumes. There was discussion at the last Developer Conference about publishing IM and tech notes on CD/ROM. I'm always looking for that piece of information that I saw somewhere but can't remember whether it was in IM somewhere or in a tech note. I'd love to be able to do quick machine searches for for information. Also consider the cross-referencing possibilities. Two problems that come to mind are the cost of the CD/ROM player and the inability of single machine developers to look up something while rummaging around in memory after a system bomb. Marsh Gosnell lzma!mkg
daw@houxs.UUCP (David Wolverton) (10/28/88)
In article <19510@apple.Apple.COM>, mjohnson@Apple.COM (Mark Johnson) writes: > ... (how many people are still using phone books?). My hand is raised (but then, hey, I'm just a "user" who occasionally needs a reference book and can't justify the cost of the A-W set). Dave Wolverton att!houxs!daw
daw@houxs.UUCP (David Wolverton) (10/28/88)
If you go the loose-leaf route, please be sure to have a numbering scheme set up right from the start, so that at any point in time it will be possible to publish an unambiguous list of the "correct" pages for a complete IM. EVERY PAGE should have a unique, unambiguous "serial" number printed on it. [As background, I occasionally get update pages for a loose-leaf reference book at home. It is often difficult to distinguish the "new" from the "old" page, especially if I didn't get around to installing the last set of pages, because there is no indication on the pages themselves of any sort of version number, date, etc. Dave Wolverton
jim@eda.com (Jim Budler) (10/28/88)
In article <16035@agate.BERKELEY.EDU> lippin@math.berkeley.edu 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? Go for it. I have an early Inside Mac Hardback. You know the one that's missing page II-92. jim -- uucp: {decwrl,uunet}!eda!jim Jim Budler internet: jim@eda.com EDA Systems, Inc.
ech@poseidon.ATT.COM (Edward C Horvath) (10/28/88)
From article <6301@claris.com>, by drc@claris.com (Dennis Cohen): > My opinion of loose-leaf vs. perfect-bound is that for something like IM that > I want to keep open next to me while I'm working dictates loose-leaf... Right on, Dennis. This, along with the ease-of-update, makes loose-leaf my choice as well. I continued to use my old loose-leaf IM until v.5 made it impossible to ignore the march of time (prior to the bound A-W versions, Apple had indeed sent out loose-leaf updates to IM: I installed the IM-4 version of File Manager right into the binder, where it belonged -- another vote for looseleaf! =Ned Horvath=
wdh@well.UUCP (Bill Hofmann) (10/28/88)
In article <3300@utastro.UUCP> werner@utastro.UUCP (Werner Uhrig) writes: > I should have been done loos-leaf to start, and it is not too late > to do it *RIGHT* ... I repeat what I said in 1984: Manuals is one > thing you should learn from IBM ... It *was* loose-leaf to begin with, and it was a giant step forward in my opinion to have it bound. Yes, indeed, delta hardbound editions are a pain. However, I think that Apple has done a pretty good job of making them only a minor pain. I'd like to see a revised IM with the machine-specific stuff integrated, and with them tastefully indicated. Most of the stuff in inside mac is correct, so the integration would be pretty simple, if you ask me. Certainly no harder than releasing a full-blown application 8->. I think the bound volume/frequent tech notes combination is a good one, especially if Apple does a better job of indexing. What's intriguing is the possibility of a CD-ROM version, with regular updates. It might even be worth springing for an Apple CD to have instant access to IM. -Bill
clyde@ut-emx.UUCP (Head UNIX Hacquer) (10/28/88)
Ahem. My first copy of "Inside Macintosh" WAS looseleaf and filled three 2-1/2 inch binders. I recall the excitment when the first 'phonebook' version IM came out -- "Wow! I can carry IM around without streching my arm out of shape!" Everything does go in cycles... -- Shouter-To-Dead-Parrots @ Univ. of Texas Computation Center; Austin, Texas clyde@emx.utexas.edu; ...!cs.utexas.edu!ut-emx!clyde "You really have to take a broad perspective when giving pat answers to other people's problems." - Eyebeam
shane@chablis.cc.umich.edu (Shane Looker) (10/28/88)
In article <1018@netxcom.UUCP> dmcintee@netxcom.UUCP (Dave McIntee) writes: >The arguments seen in this forum in favor of a loose-leaf format, and >those in favor of a bound edition are both valid, so Apple must decide >carefully. > >As a proprietary operating system, unlike Unix, the Macintosh OS is >free to evolve as Apple sees fit. They alone determine its future course, >for better or worse. While the system is very usable today, there is >sure to be a steady improvement in the years ahead. The issue is how to >best manage the dissemination of information regarding 1) changes to the >OS, and 2) the complete current documentation set at any given moment. >These two objectives should be as economical and as useful to both Apple >and the development community as possible. As has been pointed out, allowing Apple to change the rules in the middle of the game is not going to be easy. I just wrote some code which worked fine with the System 5.0 release but did not work correctly under System 6.0 There is nothing in the TechNotes to indicate that the ListManager changed, yet I am pretty sure that it did somehow. The ability to make retroactive changes to documentation is very dangerous. Superseded information replaces old information. Things do get lost this way. I've seen it happen. The only way to guarantee that your code was right is to keep all of the old pages you replace. >Considering all this, I feel that the approach taken by other vendors of >proprietary systems would be best for Apple: That is, a loose-leaf >documentation set which can be updated as needed, with the updates >provided from one source, probably Apply Computer, on an annual >subscription basis. This is provided the update subscription fee is >reasonable, say in the $25-50 per annum range, so the individual >hobbiest will not be squeezed out. Whoa there. $25.00 per year is the same price as bying a new Volume V each and every year. Probably the best way to handle the whole problem is to issue a revision book (in looseleaf form maybe) every year. That would allow Apple to collect all changes and updates and then publish them for about $10-15, since they probably won't be as large as Volume III. Yes things change, but I would be extremely worried if they changed enough that I would need to replace a substantial portion of my old documentation every year. >Developers who choose to purchase the documentation set but not subscribe >to the annual subscription service, can of course do so, and should be >able to, at any future time, obtain an update set to bring them up to >date. The cost of this should be somewhere between the annual >the wholesale price for the entire document. This will protect their >investment without forcing participation in the annual service. With my proposal, they can buy the update book for each year as needed. These are like the Year Books you get with your encyclopeadia. Nice to get but probably not heavily needed. >As for Tech Notes, perhaps they go away, but that's another matter. The Tech Notes would still be needed as the incremental information updates. >Dave McIntee I have a set of the original loose-leaf verison of IM, the phone book edition, and the AW edition. I by far prefer the softbound AW copies because they let me open multiple volumes at once and take up less space than the loose-leaf versions. Shane Looker | Looker@um.cc.umich.edu America works less, when you say "Union Yes!"
ech@poseidon.ATT.COM (Edward C Horvath) (10/28/88)
From article <1138@lzsc.ATT.COM>, by mkg@lzsc.ATT.COM (Marsh Gosnell): ... > There was discussion at the last Developer Conference about publishing > IM and tech notes on CD/ROM... In the meantime, you can get the IM Cross Reference on disk from APDA, and the current TechNote index from APDA or various other sources (including comp.binaries.mac this week!) so if you have grep/search/gofer you can find things fast anyway. Of course, I went out and got the hard-copy xref as well: paper still has much higher browsing bandwidth than electronic when you don't know what you're looking for... =Ned Horvath=
gandreas@umn-d-ub.D.UMN.EDU (Glenn Andreas) (10/29/88)
In article <548@poseidon.ATT.COM> ech@poseidon.ATT.COM (Edward C Horvath) writes: >From article <6301@claris.com>, by drc@claris.com (Dennis Cohen): >> My opinion of loose-leaf vs. perfect-bound is that for something like IM that >> I want to keep open next to me while I'm working dictates loose-leaf... > >Right on, Dennis. This, along with the ease-of-update, makes loose-leaf >my choice as well. I continued to use my old loose-leaf IM until v.5 made >it impossible to ignore the march of time (prior to the bound A-W versions, >Apple had indeed sent out loose-leaf updates to IM: I installed the >IM-4 version of File Manager right into the binder, where it belonged -- > >another vote for looseleaf! > >=Ned Horvath= Well, I've got just about all versions of IM - the two volume old loose-leaf one, the phone book, and a complete set of the bound editions (including the original hardcover IM 1-3). And then there is the notebook that I have my punched copies of Tech notes in. And none of them are perfect. I liked the ability to replace things in the old loose-leaf one, such as the file manager chapter, but I normally use the bound hardcover 1-3 in "everday use". It stays open where I want it just find, unlike the 4 & 5, and even though the file manager, etc.. is out of date, I just look in the newer ones, usually having to look in all three. But the problems with the loose-leaf things is: It's big & heavy! It takes more space open that the bound editions, since it has the big binder. I also have this problem with some of the binders that I put the MPW manuals in. It's heavy, heavier than the hardcovered book. I can set the hardcover on my lap and be able to read it while I type, or set it on a nearby chair, without a problem. The biggest problem with binders is that they are often a pain to close, especially when they are full. Pages jam, etc... I realize that going to a more expensive "side" binder would help, but then that thing is even bigger! I don't have the space. Ideally, (and someone already suggested this) I would like to see the thing in smaller pamphlets (say one per chapter) that would be punched for storage, but removed and lay flat for use. Alternately, for loose-leave manuals, rather than the big 8 1/2" x 11" pages, use those smaller pages that fit in smaller binders. They are much less bulky, and work just as well (although they are difficult to photocopy). Like the old Lisa Workshop manuals were. I seem to remember some Prodos tech manuals in that size as well. They were small and easy to find things in, they lay flat, etc... Everything I would be looking for. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= = "Whether you like it, or don't like it, sit | - gandreas@ub.d.umn.edu - = = back and take a look at it, because it's the | Glenn Andreas = = best going today! WOOOOoooo!" - Ric Flair | = =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
tomj@oakhill.UUCP (Tom Johnson) (10/29/88)
Many moons ago, I was in the Air Farce (sic). Air Force manuals are both one of the BEST and WORST things about the service. All manuals are loose leaf, and updates are handled by supplying new pages as required, with changed material denoted by a heavy black line in the margin. Additionally, each update comes with a "List of Effective Pages" page. While the new CONTENT pages are many times replaced, it is required that each manual keep all copies of all "List of Effective Pages" pages. Many times, we kept the replaced pages (when the changes were other than grammatical) in a separate binder, so that if we wanted to "back track" a problem, we had all relevant documentation from ALL revisions back to day 1, while the "main" manual contained only the most recent info. Replacement pages were always marked in the upper border with not only the page number, but also the revision number of that page (which made it easy to check the "effective page" pages to determine what the last rev of that page was). This system WORKS, but requires a little effort on the part of the user. In the service, the effort to maintain about 100 manuals amounted to a few minutes (up to say 1/2 hour) per revision, and we were graded on whether or not all manuals were "up to snuff". This system is used in the service to keep manuals ranging from "How to type a proper letter" to "How to service a B1 Radar System" completely up-to-date.--(the bad part is that they are all written for 6th graders to read :>). --Tom Johnson, Motorola |Disclaimer: A single glance will tell that I tomj@oakhill.UUCP | obviously don't speak for Motorola.
rang@cpsin3.cps.msu.edu (Anton Rang) (10/29/88)
If loose-leaf manuals are put together well, they're a real joy to use. They can also be quite awful, even if the material is good. For an example of very good loose-leaf manuals (in my opinion), check out the VMS documentation. Heavy paper and large binders (D-ring, which lets it stay open at the right place!). Page formats are clear and consistent. Changes between versions are clearly marked with change bars at the appropriate places. In addition, the "Release Notes" give a summary of what's changed since the last release. If I have to use cheap loose-leaf manuals with thin paper (as one major UN*X vendor provides), life's miserable (but then, Unix manuals are awful anyway). Heavy loose-leaf, together with good binders (think D-rings...think Apple should sell binders with a nice Apple logo on them...optional, of course, so you could use your own binders) would be nice, though. Just my thoughts.... +---------------------------+------------------------+----------------------+ | Anton Rang (grad student) | "UNIX: Just Say No!" | "Do worry...be SAD!" | | Michigan State University | rang@cpswh.cps.msu.edu | | +---------------------------+------------------------+----------------------+
pengo@tmpmbx.UUCP (Hans H. Huebner) (10/30/88)
In article <975@cps3xx.UUCP> rang@cpswh.cps.msu.edu (Anton Rang) writes: > If I have to use cheap loose-leaf manuals with thin paper (as one >major UN*X vendor provides), life's miserable (but then, Unix manuals >are awful anyway). I don't share this opinion. I'd be very happy if the Macintosh Docs would be in the standard Unix manual format. Unix manuals are for programmers, and they are only reference. Once you learned how they work, they are very useful. In fact, I find them much easier to use than the VMS docs, since I never need more than some seconds to find exactly the information I need. Another good thing about the Unix manual scheme is that they're very easy to update. Ok, I know that this is the wrong place to start another UNIX vs. VMS war ;-). > Heavy loose-leaf, together with good binders >(think D-rings...think Apple should sell binders with a nice Apple logo >on them...optional, of course, so you could use your own binders) >would be nice, though. Yep. I'd love to see the Mac docs splitted in two parts: A section with full-blown, easy to understand usage information for each part of the toolbox, and a reference section, maybe similar to the Unix manuals, splitted into sections for every toolbox manager. As such, a newcomer would read the introduction to the Mac first, and later on he'd only use the reference sections for quick and easy access. That's the way Unix manuals work, and I don't know too many Unix programmers who have difficulties with the manuals. My major complaint about the Mac is the bad documentation. A better scheme could be helpful in getting rid of the prejudice that the Mac is hard to program. -Hans -- Hans H. Huebner, netmbx | PSIMail: PSI%026245300043100::PENGO Woerther Str. 36 | DOMAIN: pengo@tmpmbx.UUCP D-1000 Berlin 20, W.Germany | Bang: ..!{pyramid,unido}!tmpmbx!pengo Phone: (+49 30) 332 40 15 | BITNET: huebner@db0tui6
steve@ivucsb.UUCP (Steve Lemke) (10/31/88)
In article <1027@houxs.UUCP> daw@houxs.UUCP (David Wolverton) writes: } }If you go the loose-leaf route, please be sure to have a numbering scheme }set up right from the start, so that at any point in time it will be }possible to publish an unambiguous list of the "correct" pages for a }complete IM. EVERY PAGE should have a unique, unambiguous "serial" number }printed on it. } Do they really need some "serial" number? I agree that a page numbering scheme needs to be thought out, but that could just be something like "section.sub-section.page.addon" where "section" is perhaps the toolbox manager section number, the "sub-section" might be a certain command procedure, the "page" number would be the original page number, and the "addon" would be for future additions between pages (where the actual pages involved didn't need to be reprinted, although if it became necessary for "addon.addon" (etc.) then the sub-section might better be reprinted (and renumbered as well) and distributed. }[As background, I occasionally get update pages for a loose-leaf reference }book at home. It is often difficult to distinguish the "new" from the "old" }page, especially if I didn't get around to installing the last set of pages, }because there is no indication on the pages themselves of any sort of version }number, date, etc. } It seems to me that if the date is printed on each page, then it shouldn't be any big deal to determine which page is "new" and which page is "old". Also, a list could be distributed of pages and the corresponding "dates" of their last revision. Then you would know which of your pages are out of date, so to speak. In fact, the table of contents could have the latest dates of each section and sub-section. }Dave Wolverton ----- Steve Lemke ------------------- "MS-DOS (OS/2, etc.) - just say no!" ----- Internet: steve@ivucsb.UUCP; lemke@apple.COM AppleLink: LEMKE ----- uucp: pyramid!comdesign!ivucsb!steve CompuServe: 73627,570 ----- alt.uucp: {decwrl!}sun!apple!lemke GEnie: S.Lemke ----- Quote: "What'd I go to college for?" "You had fun, didn't you?"
mystone@caen.engin.umich.edu (Dean Yu) (11/01/88)
How does this sound? Apple can set up anonymous FTP at Apple.Com, and chop Inside Mac into little sections, and put them up for grabs for anyone who has access to the net. Since almost everyone and his brother can get onto a network these days, I don't see this as a big problem. Then, we can grab whichever sections we need. No more trying to remember which chapter deals with the Slot Manager, or which volume talks about the Memory Manager. This also effectively solves the debate about whether Inside Mac should be distributed as loose leaf or bound. Once we download it, we can stick it in a binder, or have it bound at the nearest Kinko's Copiers. We also wouldn't have to worry about everyone having different versions. Since the sections would be coming from one source, namely Apple, anybody who wants to make it in the Macintosh community will keep updated versions of whatever sections they need. Apple of course, would pull outdated versions off, and replace them with newer versions as necessary. I realize that there ARE some people who don't have access to a computer on the net. For those few, Apple can continue marketing Inside Macintosh in its current incarnation, and THAT will keep Apple happy, since it gives them a profit margin that anonymous FTP wouldn't. ;) And since those people outside of netland don't have access to the net, they don't realize that this whole debate has been raging on for who knows how long, and wouldn't miss a thing! (What they don't know won't hurt them...) So how about it, Apple? I can see this as a great way to get a very large amount of beta testers, too, for newer systems and whatnot if you don't limit this anonymous FTP idea to just Inside Mac! ______________________________________________________________________________ Dean Yu | E-mail: mystone@caen.engin.umich.edu University of Michigan | Real-mail: Dean Yu Computer Aided Engineering Network | 2413 Kelsey House ===================================| 600 E Madison "These are MY opinions." (My | Ann Arbor, MI 48109 employer doesn't want them. |========================================== Actually, they don't really care | what I think. But President | This space intentionally left blank. Duderstadt does...) | ------------------------------------------------------------------------------
koehn@gumby.cs.wisc.edu (Brad Koehn) (11/01/88)
No! Please! Don't put Inside Macintosh in loose leaf! I just spent about $30 on my copy of the Programer's Online Companion (Addison Wesley), and would like to have the page numbers (that the program supplies with an entry) have some meaning! Brad Koehn
jrk@s1.sys.uea.ac.uk (Richard Kennaway CMP RA) (11/01/88)
For ease of updating, nothing beats loose leaf. For ease of handling and robustness, nothing beats a properly bound book. Trouble is, what we have at present is bound books plus a pile of scattered TNs and no easy way of finding where the latest version of some piece of info is. Now, I dont want to start a religious war, but... In article <1282@tmpmbx.UUCP>, pengo@tmpmbx.UUCP (Hans H. Huebner) writes: > I'd be very happy if the Macintosh Docs would be in the standard Unix > manual format. ... I don't know too many Unix programmers who have > difficulties with the manuals. By definition, a Unix programmer is someone who has learnt where to find things in the Unix manuals :-) > Once you learned how they work, they are very useful. I couldnt have expressed it better :-) The best feature of IM is the index. From day one of programming the Mac, I have rarely had any difficulty in locating information in IM (when it is there :-). This is not true of TNs. I would like to see a single joint index to all the volumes of IM and all the TNs, in the same level of detail as the current IM indexes, a new version of the whole index going out with each distribution of TNs. TN0 just isnt good enough. On the whole, I would prefer bound volumes + index as above, but I can see the strong arguments for loose-leaf (I'd still want that index, though). If Apple goes for loose-leaf, *please* attend to the physical quality of the binders. There is nothing more frustrating than handling binders with (a) too much paper stuffed into too small rings (b) punched holes too small to let the pages turn freely (c) holes too close to the edge, so the pages get torn out (d) covers that stick to the outside sheets and tear them out. And one small point that has nothing to do with bound vs. loose leaf: please use Times instead of Helvetica for TNs. Easier to read and you get more on a page. (No, I dont know about typesetting, I just know what I like.) -- Richard Kennaway School of Information Systems, University of East Anglia, Norwich, U.K. uucp: ...mcvax!ukc!uea-sys!jrk Janet: kennaway@uk.ac.uea.sys
dorourke@polyslo.CalPoly.EDU (David M. O'Rourke) (11/02/88)
In article <1282@tmpmbx.UUCP> pengo@tmpmbx.UUCP (Hans H. Huebner) writes: >My major complaint about the Mac is the bad documentation. A better scheme >could be helpful in getting rid of the prejudice that the Mac is hard to >program. I wouldn't call the macintosh's documentation bad! In fact compared to most of the other windowing systems that I've seen {MS-Windows, X, & NeWS} I'd say that it's quite good! And the prejudice that the Mac's hard to program is also found in other windowing systems as well. Most programmers aren't used to event driven programming and it takes quite a bit to make the mind shift necessary to do it effectivly. But to call the Mac's documentation "bad" is inappropriate in my opinion. p.s. That's not to say it couldn't be improved upon ;-) -- David M. O'Rourke dorourke@polyslo.calpoly.edu "If it doesn't do Windows, then it's not a computer!!!" Disclaimer: I don't represent the school. All opinions are mine!
gsbrob1@apcvxa.uchicago.edu (11/02/88)
>For ease of updating, nothing beats loose leaf. For ease of handling and >robustness, nothing beats a properly bound book. Trouble is, what we have >at present is bound books plus a pile of scattered TNs and no easy way >of finding where the latest version of some piece of info is. > >The best feature of IM is the index. From day one of programming the >Mac, I have rarely had any difficulty in locating information in IM >(when it is there :-). This is not true of TNs. I would like to see a >single joint index to all the volumes of IM and all the TNs, in the >same level of detail as the current IM indexes, a new version of the >whole index going out with each distribution of TNs. TN0 just isnt >good enough. > In general a bound book is more robust, but my paperback IM 1 hasn't held up all that well. Each chapter has more or less fallen out on it's own. Ah well, I guess it's time to spring for a new copy. :->. One piece of info about the index: there's a book put out by Apple/A-W called "Inside Macintosh X-Ref" which indexes all 5 volumes of IM, Tech notes thru '87 I think, and about 3 other new tech references put out by Apple. It's about $10 over here. Of course it's not completely up to date, but it might be helpful to you. Robert gsbrob1@apcvxa.uchicago.edu ra_robert@gsbacd.uchicago.edu ............................................................................ . generic disclaimer: all opinions here expressed are mine and mine alone . ............................................................................
Mike_G_Newman@cup.portal.com (11/02/88)
Here we go re-inventing the wheel on this topic. There must be many organizations who have dealt successfully with the problem of presenting instructional or operational material that changes from time to time. I happen to work for a large government agency whose operational manuals cover about 15 feet of shelf space. We use a loose leaf system along with numbered "tansmittals" that are used to update specific sections. You keep track of transmittal numbers to make sure that each section is up- to_date. Pages are numbered with a decimal system that includes the section and subsection in the whole number part and the 'page' number in the decimal part. Letters are added if an extra page gets inserted. It is always easy to tell if a section is 'whole'. Since the page number tells you exactly where you are, specific references are independent of the actual number of pages. (Does that make sense?) On the negative side, keeping the thing up-to-date is a pain. Our agency has tried and abandoned a number of alternatives: perfect bound among them. It seems to be cheaper and more efficient to use the loose leaf format. However, if discipline declines, the system fails. We also use a system in which 'program notes' are distributed which are not interfiled with the manual, but which explain specific and perhaps timely topics or which are reminder items. These can be created and distributed more quickly then manual revisions and generally have a specific and limited life time. Any thoughts from other organizations? mike_g_newman@cup.portal.com
jordan@Apple.COM (Jordan Mattson) (11/03/88)
Dear Richard - If you are looking for an index to all of Inside Macintosh and the Technical notes, you should check out the Inside Macintosh X-Ref. It is wonderful! It indexes and cross references all five volumes of Inside Macintosh, Programmer's Intro to the Macintosh, Technical Intro to the Macintosh, Designing Cards and Drivers, and the Macintosh Technical Notes. Jordan Mattson UUCP: jordan@apple.apple.com Apple Computer, Inc. CSNET: jordan@apple.CSNET Tools & Languages Product Management 20525 Mariani Avenue, MS 27S Cupertino, CA 95014 408-973-4601 "Joy is the serious business of heaven." C.S. Lewis
daw@houxs.UUCP (David Wolverton) (11/03/88)
In article <360@ivucsb.UUCP>, steve@ivucsb.UUCP (Steve Lemke) writes: > In article <1027@houxs.UUCP> daw@houxs.UUCP (David Wolverton) writes: > }EVERY PAGE should have a unique, unambiguous "serial" number > }printed on it. > } > Do they really need some "serial" number? I agree that a page numbering > scheme needs to be thought out, but that could just be something like > "section.sub-section.page.addon" where "section" is perhaps the toolbox > manager section number, the "sub-section" might be a certain command > procedure, the "page" number would be the original page number, and the > "addon" would be for future additions between pages (where the actual > pages involved didn't need to be reprinted, although if it became necessary > for "addon.addon" (etc.) then the sub-section might better be reprinted (and > renumbered as well) and distributed. > > It seems to me that if the date is printed on each page, then it shouldn't > be any big deal to determine which page is "new" and which page is "old". > Also, a list could be distributed of pages and the corresponding "dates" of > their last revision. Then you would know which of your pages are out of > date, so to speak. In fact, the table of contents could have the latest > dates of each section and sub-section. Sigh. I guess I wasn't clear enough. All I'm asking is that it be possible to unambiguously determine the vintage of each page, and to unambiguously list all the pages in what is the "current set of pages" at any point in time. Dave Wolverton
mls@dasys1.UUCP (Michael Siemon) (11/03/88)
In article <1936@puff.cs.wisc.edu>, koehn@gumby.cs.wisc.edu (Brad Koehn) writes: > No! Please! Don't put Inside Macintosh in loose leaf! I just spent about > $30 on my copy of the Programer's Online Companion (Addison Wesley), and would > like to have the page numbers (that the program supplies with an entry) have > some meaning! Any decent looseleaf scheme (and I urge the adoption of one) has a sort of hierarchical numbering, so that page numbers do NOT become obsolete. Now, that might muck up an already purchased cross-reference on its first being imlemented -- but then you should be able to get an update for such a one- time change from a decent commercial supplier. -- Michael Siemon I cannot grow; Big Electric Cat Public UNIX I have no shadow ..!att!mhuxumls To run away from, ..!uunet!dasys1!mls I only play.
riley@beowulf.ucsd.edu (Christian Riley) (11/03/88)
Mike_G_Newman@cup.portal.com writes in <10785@cup.portal.com>: >Here we go re-inventing the wheel on this topic. There must be many >organizations who have dealt successfully with the problem of presenting >instructional or operational material that changes from time to time. Yes, others have worked on similar problems. For example, when IBM was working on the OS/360 project, they had about 1000 people working on the design and technical aspects. (these facts and quotes are from "The Mythical Man-month", essays on Software Engineering, Frederick Brooks). Anyway, this is essentially the same problem: trying to keep >>1000 people needing to see all the material. Here are a few applicable quotes: " Of critical importance is timely updating. The workbook [or Technical description] must be current. This is very difficult to do if whole documents must be retyped for changes. In a looseleaf book, however, only pages need to be changed." ... "The recipient of all these updated pages has an assimilation problem, however. When he receives a changed page, he wants to know, 'What has been changed?'...and 'What is the definition today?'" "Our project had not been under way six months before we hit another problem. The workbook was about 5 feet thick!" ... "Furthermore, the daily change distribution averaged 2 inches, some 150 pages to be interfiled in the whole. Maintenance of the workbook began to take a significant time from each workday." One difference was they had revisions much more often, but it was to a smaller number of people, closer together geographicly. So maybe it balances? Well, he goes on to discuss other solutions such as microfiche (and its problems). He also discusses how he would do it today. So, yes, there are people who have dealt with this and I'm sure there probably are many other books discussing similar problems, and perhaps Apple will come up with a nice solution! "Free scientific inquiry? The first adjective is redundant." Chris Riley riley@cs.ucsd.edu
steve@violet.berkeley.edu (Steve Goldfield) (11/04/88)
Maybe I'm spoiled by UNIX--and I admit that I haven't seen Inside Mac--but isn't one obvious solution to keep it on disks or in a downloadable format, at least for frequent updates. Then there would be an aftermarket for a utility which helps find the relevant pages. man and apropos are very helpful in navigating UNIX; why not implement them for the Mac? Steve Goldfield
kehr@felix.UUCP (Shirley Kehr) (11/04/88)
In article <10785@cup.portal.com> Mike_G_Newman@cup.portal.com writes: >Pages are numbered with a decimal system that includes the >section and subsection in the whole number part and the 'page' number >in the decimal part. Letters are added if an extra page gets inserted. >It is always easy to tell if a section is 'whole'. Unless you also supply a list of effective pages, no one can tell whether they have the pages inserted between "page numbers" (the a, b, etc. pages). >On the negative side, keeping the thing up-to-date is a pain. That's an understatement! >However, if discipline declines, >the system fails. I'm not sure whose discipline you're referring to, but it's a well-known fact that the recipients of the change pages do not religiously update their manuals. Then they leave the company and the next person gets stuck with a mess. We had the ridiculous situation of sending three change packets in a row for a programming manual before incorporating all those changes into a new manual. User's paid by the page for the updates. Since we did not collate change pages into stock, new users got a manual with instructions to insert and remove 20 to 40 pages. Then they went to the next update and removed many of the pages just inserted in order to bring the manual up to the next level. Finally they went to the third update received with their "new" manual. It's awful what we ask new customers to do sometimes. At FileNet, we have decided to update only whole modules (pretty much like chapters) at once. There are no section numbers. Each module in the handbook is a standalone piece--easy for us--easy for them. But, there is still a downside, and that is the lack of an overall index. I'd like to hear suggestions on how to refer to certain pages in certain modules in one or more manuals. Note that we're just starting this program and have no experience in managing it nor feedback from customers. Shirley Kehr >We also use a system in which 'program notes' are distributed which >are not interfiled with the manual, but which explain specific and >perhaps timely topics or which are reminder items. These can be >created and distributed more quickly then manual revisions and >generally have a specific and limited life time. > >Any thoughts from other organizations? > >mike_g_newman@cup.portal.com
norbert@iraul1.ira.uka.de (Norbert Lindenberg) (11/05/88)
In article <19865@apple.Apple.COM> jordan@Apple.COM (Jordan Mattson) writes: > If you are looking for an index to all of Inside Macintosh and >the Technical notes, you should check out the Inside Macintosh X-Ref. >It is wonderful! I agree. Especially the machine-readable form is very useful. Is Apple going to release up-to-date revisions??? -- Norbert
suitti@haddock.ima.isc.com (Steve Uitti) (11/05/88)
In article <3f64757b.1285f@maize.engin.umich.edu> mystone@caen.engin.umich.edu (Dean Yu) writes: > > How does this sound? > Apple can set up anonymous FTP at Apple.Com, ... I'd really like to have a machine readable version of Inside Mac. Having it available via FTP or UUCP or just dialin would be nice, but I don't think Apple would go for it. I suppose I could call California (from Boston) at midnight, set up the transfers and go to sleep... It might not be finished in the morning. Kermit tends to get about 70 CPS throughput for this sort of thing. That's only about 2 MB in eight hours. IF I had a 2400 baud modem, and IF I could get 240 CPS continuous throughput, it would still be only 8 MB per night. It would be a hassle. It would not be free (I'd pay the phone company, I'd be adding overhead to Apple, which I'm sure would be reflected in my next Apple purchase). Then you want me to print it? How long will that take on an Imagewritter II? How much will that cost me (paper ribbons, Imagewritter II's)? OK, so I have a laser printer. I still would want to print it double sided so that it wouldn't be five feet thick. To my knowledge, USoft Word doesn't have a "print double sided" option (the one I want is where you print the odd pages, then print the even pages), so I'd have to manually feed each page, flipping it by hand. And of course, you have to use better (more expensive) paper for double sided work (otherwise the paper gets mutilated & causes paper jams). Then I'd bring the result to Kinko's (copy shop) and have it edge bound (notebooks are so cumbersome and the pages come out when reading on the subway on the way to work). There. Done. And its almost as cheap and high quality as going down to Wordsworth and buying it outright. Of course, I bought IM I-V and the Human Interface Guidelines. I wish I could pick up the technotes at my local bookstore. I'm almost done reading IM Vol I. I constantly refer to it. Apple might go for selling disks. I haven't the foggiest notion of how many 800K disks this would take. It might make an excellent CD ROM application. For that matter, it might make a good CD & Hypercard application. All sorts of built in cross referencing and searching... It might be the application that would get me to buy a CD drive (though I'm hoping that WORM or WMRM optical technologies will win). If more developers have CD drives, more developers will be tempted to market stuff for them. Microsoft is doing something like this (I got something in the mail recently). I don't recall exactly what the documentation was about, though it either had something to do with OS/2 or uSoft C. Stephen.
rmf1992@uxf.cso.uiuc.edu (11/06/88)
(.02 following)
I would just like to suggest a comprimise between the loose-leaf format
and the perfect bound book. Most of the responses have said that loose-leaf is
better, but ... diffucult to keep manual and index updated, losing and tearing
of pages, and needing larg binder(s). Someone suggested a pamphlet type system
and this sounds excellent. First of all these can be simply made strong enough
to not even need a binder and survive on their own, but obviously they could be
put into a binder if you want. Since they will be somewhat bound you don't have
the same chance of losing a single page (but then again sometimes I can't find
my IM's). And the problem with updating can be made very efficient by
giving each chapter its own pamphlet or 3, and if the chapter has more than one
pamphlet then a cross between handwaving and a little foresight could
concentrate the material that is most likely to have updates in one of the
pamphlets. And of course a new index would be published with each set of
updates. Perhaps, this would become a regular notification channel being
published quartely or semi-anually, supplemented inbetween updates with tech-
notes.
-----------------------------------------------------------------------------
Bob Frank | Disclaimer: |
- struggling undergrad | Nobody understands my opinions anyways! |
at the University of |-----------------------------------------------|
Illinois | Remember: |
----------------------------| 2 == 1; /* for very small values of 2 */ |
Send Mail to: |-----------------------------------------------|
rmf1992@uxf.cso.uiuc.edu |
----------------------------|zcnj01@gpb6.uucp (Cecil N. Jones) (12/21/88)
I am a new Mac user. Please tell me what Inside Mac is,
and how do I get access to it.
Thanks -
Cecil N. Jones Amoco Production Co. Tulsa, OK
@apctrc.uucp
The opinions expressed are solely my own.peterson@peterson.applicon.UUCP (01/05/89)
Inside Macintosh is a collection of books for Mac programmers covering
many aspects of the Mac & operating system. They are available at
many computer stores.
Joe Peterson
Schlumberger Technologies
Billerica, MA
email: peterson@applicon.com
Disclaimer: My company has nothing to do with what I say here, nor does
it use any other bizarre forms of mind control.sbj421@leah.Albany.Edu (S B Jacobson) (07/13/89)
Forgive my naivite, but just what exactly is Inside Mac V I-?? Where does one find it? It sounds like something that no Mac programmer should be without, but here I am programming on a Mac, and I don't even know what it is! Any help would be appreciated. Thanx in advance. +=============================================================================+ | - Steve Jacobson - | "Today there is no day or night ^ | +=========================+ Today there is no dark or light / | \ | | SBJ421@ALBNYVM1.BITNET | Today there is no black or white ( /|\ ) | | sbj421@leah.albany.edu | Only Shades of Grey" \ | / | | SBJ421@ALBNYVMS.BITNET | -The Monkees v | +=============================================================================+ |Disclaimer: I'm just a student. Nobody listens to me anyway. If you don't | |like these opinions, just ignore them. I'm sure they'll just go away. | +=============================================================================+
awd@dbase.UUCP (Alastair Dallas) (07/14/89)
I can't believe you didn't get a reply earlier. Inside Mac is a series of books published by Addison-Wesley and available in technical bookstores as well as chains such as B.Dalton across the country. They are somewhat expensive, so some get by with just a few volumes. Volumes I, II and IV are vital. III is hardware and summary and V is color, essentially. Volumes I, II and III are available bound together--IV and V update the earlier volumes. There is also a comprehensive index available (another book). When you see a reference to II-254, they mean page 254 in volume II of the set. You can get along with the IM books if you have someone else's technical reference, but since that book will have been based on Inside Mac, most serious programmers want the original available, as well. However, it is somewhat frustrating that IM is all Pascal with some assembly. There have been some good Mac tech refs published which describe the toolbox in either C or assembly language, which is clearly more useful if that's your native tongue. Get-a your Inside Mac! Can't tell the ROMs without-a your Inside Mac! /alastair/
jb28+@andrew.cmu.edu (Jeffrey Joseph Barbose) (07/14/89)
Steve, Inside Macintosh (vols I-V) is the definitive reference for Macintosh Toolbox and OS functions, procedures, and utilities. It groups all of these into their respective Managers, such as the Window Manager, Desk Manager, Memory Manager, Resource Manager, etc. It lists the functions available, describes the function and interface to each, and lists the call to each in Pascal. Notes are included for Assembly Language programmers. Vols I-III are about the classic (Plus and pre-Plus) Macintoshes, vol IV-V include the updates to the Toolbox and OS introduced with the SE and the II. I'm going through them right now, and it's not easy. If you want to approach it from what's currently available, you have to read through vol I (say, about the Resource Manager) and then lookup the updates in vol 4-5. I'm just going to read through them, vol by vol., and try to assimilate all of it as I go. There is a cross-ref available, called XREF. All of these volumes (including XREF) are published by Apple Computer, and should be available at bookstores which have an extensive Computing section, or through TechAlliance (you'll have to call Renton, WA information to get the number) or through APDA (Apple Programmers and Developers Association) (800-282-APDA for customer service) I bought my through APDA (I'm a member: $20 annual), but found out that TechAlliance was cheaper than retail. Jeff p.s. If your bookstore carries MacTech Quarterly magazine, the info for joining and purchasing materials from TechAlliance is in there. Plus, it's a pretty good magazine.
hal@krishna.cs.cornell.edu (Hal Perkins) (07/14/89)
In article <4YjF0IS00WB584Bl89@andrew.cmu.edu> (Jeffrey Joseph Barbose) writes: >Inside Macintosh (vols I-V) is the definitive reference for Macintosh Toolbox >and OS functions, procedures, and utilities. > >I bought my through APDA (I'm a member: $20 annual), but found out that >TechAlliance was cheaper than retail. One other note -- If you're considering buying a full set of IM, you might want to get the looseleaf edition from APDA. It contains everything in IM I-V and the Xref, and of course you can rearrange the chapters to put the newer information in vols. IV and V near related information in the earlier volumes. Hal Perkins hal@cs.cornell.edu Cornell CS
drc@claris.com (Dennis Cohen) (07/14/89)
In article <160@dbase.UUCP> awd@dbase.UUCP (Alastair Dallas) writes: > >I can't believe you didn't get a reply earlier. Inside Mac is a series of >books published by Addison-Wesley and available in technical bookstores as >well as chains such as B.Dalton across the country. They are somewhat >expensive, so some get by with just a few volumes. Volumes I, II and IV >are vital. III is hardware and summary and V is color, essentially. >Volumes I, II and III are available bound together--IV and V update the >earlier volumes. There is also a comprehensive index available (another >book). > Not wanting to contradict my friend and former coworker (Alastair), but the comment about Volume V that appears above is misleading. If you want to deal with Styled TextEdit, Hierarchical/Popup Menus, the Notification Manager, and a number of other things that appeared with the Mac II and Mac SE, you need Volume V. You also need the TechNotes (available from many of the archive sites or APDA) if you want to do real work as they tell you what errors exist in IM as well as what has changed. -- Dennis Cohen Claris Corp. ------------ Disclaimer: Any opinions expressed above are _MINE_!
han@Apple.COM (Byron Han) (07/15/89)
In article <4YjF0IS00WB584Bl89@andrew.cmu.edu> jb28+@andrew.cmu.edu (Jeffrey Joseph Barbose) writes: >Steve, > >Inside Macintosh (vols I-V) is the definitive reference for Macintosh Toolbox >and OS functions, procedures, and utilities. > You will also need to get access to the Macintosh Technical Notes series which contains absolutely essential and invaluable hints and errata to the information in Inside Macintosh. The Macintosh Revealed series is a good guide to the Macintosh toolbox with lots of source code examples. Hope this helps. +-----------------------------------------------------------------------------+ | Disclaimer: Apple has no connection with my postings. | +-----------------------------------------------------------------------------+ Byron Han, Communications Scapegoat At Apple, we change the world everyday. Apple Computer, Inc. ----------------------------------------- 20525 Mariani Ave, MS27Y Internet: han@apple.COM Cupertino, CA 95014 UUCP:{sun,voder,nsc,decwrl}!apple!han ------------------------------------ GENIE:BYRONHAN CompuServe:72167,1664 ATTnet: 408-974-6450 Applelink:HAN1 HAN1@applelink.apple.COM -------------------------------------------------------------------------------
brian@cs.utah.edu (Brian Sturgill) (12/15/89)
How long before the revamp of Inside Mac. is released, I have been wanting a copy, but would like to have an up to date one. Brian brian@cs.utah.edu
mjohnson@Apple.COM (Mark B. Johnson) (12/15/89)
In article <1989Dec14.192047.13685@hellgate.utah.edu> brian@cs.utah.edu (Brian Sturgill) writes: >How long before the revamp of Inside Mac. is released, I have been wanting >a copy, but would like to have an up to date one. I hate to burst bubbles, but if you are waiting for a revised book version of Inside Mac to buy, you may be waiting longer than you hope (as we all are). If you need a copy, go get one tomorrow, it won't be obsoleted in the near future. Good news is that our Developer Technical Publications group, the group which writes and publishes ALL of our technical documentation, is looking at a very bright future. They have recently undergone some upper management changes and seem VERY receptive to feedback and suggestions for the first time in a long time. A sign of this is a two-way discussion folder on AppleLink. They will hopefully very soon have a general account to which people on the Internet and other networks can send comments and suggestions. This isn't a promise, only a hope. Don't worry though, they have already received the 45+ pages of comments from people on Usenet from last year that this newsgroup generated. Although it is very easy to complain and moan about IM and our other documentation (trust me, in DTS it is our job to complain), give this "renewed" tech pubs group a chance, and I think we might see some great things coming from them in the future. In the meantime, we'll see what we can do with Technical Notes and other documentation to try to help you out. -- 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_
schear@ttidca.TTI.COM (Steve Schear) (12/19/89)
I would guess that with System 7.0 just around the corner, Apple will wait till its release to update IM.
mjohnson@Apple.COM (Mark B. Johnson) (12/19/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_
t-jacobs@cs.utah.edu (Tony Jacobs) (12/20/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. Yeah, perhaps they'll call IM vol 7 to catch up with the numbering scheme! %} Tony Jacobs * Center for Engineering Design * U of U * t-jacobs@cs.utah.edu
lars@salt.acc.com (Lars J Poulsen) (12/23/89)
In article <37391@apple.Apple.COM> mjohnson@Apple.COM (Mark B. Johnson) writes: > ... what is the ideal Inside Mac? >Is it bound? 3-ring punched and updatable? Both? Neither? I'd like it 3-ring updateable, and have the update subscription be a feature of APDA membership. > Is it organized according to task? Manager? Alphabetically? There should be an introductory overview, followed by sections by manager, alphabetically. > Does it include Pascal AND C interfaces? How much assembly-language > information? Is it a reference manual? A tutorial? Both? Neither? Yes, it is a reference manual. It should describe the entry points in assembler, Pascal and C (but it should be practical to do this in a generic fashion rather than requiring three whole articles for each routine). But a little tutorial intro would not hurt at all. I think Inside Macintosh vol I was just the right blend. And I'd like to see a supported sample demo available in source form as a companion. TeachText sources in C and Pascal !!!! What better way to get applications developers to follow the interface guidelines than to give them working code and encourage them to copy it !!! -- / Lars Poulsen <lars@salt.acc.com> (800) 222-7308 or (805) 963-9431 ext 358 ACC Customer Service Affiliation stated for identification only My employer probably would not agree if he knew what I said !!