Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

ziggy (25)

ziggy
  (email not shown publicly)
AOL IM: ziggyatpanix (Add Buddy, Send Message)

Journal of ziggy (25)

Thursday March 24, 2005
12:08 PM

The Inside Macintosh Problem

[ #23824 ]
Years ago, I picked up a piece of jargon: The Inside Macintosh Problem. I defined it in my journal a few weeks ago:

The original edition of Inside Macintosh (later known as Inside Macintosh, Volume I) was a reference book of 25 chapters, each written with the expectation that you had read and fully understood the other 24 chapters it built on.

I don't know that I've ever seen this term in print. I went to school at a heavily Mac-centric university (starting in the days of System 6.x), and I may have picked up the term from some of my mac hacking friends (who probably picked it up from usenet, some mailing list, a magazine, whatever).

Google doesn't know much about this usage. That journal post of mine is currently within the top 20 hits for the term. (Most of the hits are what you would expect, pages that contain the term inside macintosh and the word problem.)

Has anyone else seen this usage? I really like using it because it is a concise explanation of the problem of overly self-referential technical documentation, even if the term is more than slightly obscure. It's pretty easy to explain and understand; most of us have come across at least a mild case of this problem.

As far as I know, there aren't any other examples of self-referential documentation that are widely known and predate 1984, so I suspect that this formulation has some kind of priority. But are there any other terms that pithily summarize the concept of "self-referential technical documentation"?

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • At heart I'm a "whole picture" kind of guy as opposed to an "incrementalist" i.e. it takes me longer to get to a basic level of understanding because I haven't grasped the whole picture but once I have some fuzzy sense of the whole picture I usually progress much faster then my peers.

    I've always felt that taking an inverse Russian Doll approach to documentation would be much more beneficial for the end user (if they actually ended up reading docs of course ). By this I mean have a series of progressively

    • A similar idea to having have to have read all the docu before understanding any of it is expressed by Norman Cohen in Ada As A Second Language, where he says: None of the language can be explained well before all of it has been already understood, or something.

      This applies to grammar of natural languages too, I think.