use Perl

• Documentation (Score:1)

  by milardj (4452) on 2005.03.24 12:38 (#39136) Journal

  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 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.

  Reply to This

  • Re:Documentation (Score:1)

    by mr_bean (3802)

    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.