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"?
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 larger documents to describe the application/process.
Start off with a 5-10 page overview of sub-systems/architecure/relationships/work-flow. For the next document for each page in the preceeding document have 5-10 more pages. Repeat until the final document has the level of granularity needed.
In conjuction there should be a straight reference document and a cookbook document. All documents should be crosslinked so that if I read the initial 5-10 page doc any concept would link me to several varying levels of granularity as well as examples (cookbook) and mechanics (i.e. api's within the technical reference).
I realize that the resources needed to maintain this would be large but I wonder how much would be recouped in decreased support cost.
None of this is very related to the journal entry but it came to mind since I've been spending a couple of agonizing weeks working with Merant VM documentation (thousands of pages). Thousands of pages of documentation and anything I really want to know can't be found.
Re:Documentation
mr_bean on 2005-04-04T02:23:38
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.
