I’ve developed an innate distrust of the phrase “left as an exercise for the reader” when used in technical documentation. This idiom is normally indicative of at least one of the following situations:
- The author is too lazy to cover the majority of use cases, and besides, there’s a Buffy marathon starting in fifteen minutes on the WB.
- The author is not well-informed about the subject matter, beyond what he could find on Google, and is afraid that fact might become obvious to a reader and thereby threaten his ability to keep publishing on OSDN sites.
- The author basically “lucked out” that a procedure worked for him and has no idea how it happened, much less how to explain how or why to a reader, although you can bet he’ll spend plenty of time in the forums and IRC doing so.
I imagine there is call for this phrase in academic works where the main use case for the documentation is theoretical and not practical. I distinctly remember seeing it in some of my university-level science texts. In practical technical documentation, however, I’ve found it more often to be evidence of a lazy or ignorant author.
Can you tell I’ve been doing some problem-solving today at work? Right, I thought so. Must… restrain… Fist of… Death….
situation #3 reminds me of the proofs we were forced to do in 9th grade geometry. so often i could arrive at an answer, yet not be able to elucidate the process that brought about that arrival. and i had one of those teachers that gave 0% credit for a correct answer sans the proof. grr!