Compartilhar via

Documentation-Driven Development

  • Artigo

A former manager poses a provocative idea: end-user help topics for all new applications and features--like the sweet new Source Control Explorer window in Microsoft Visual Studio 2005 Team System--should be written before development begins;  Help First or Documentation-Driven Development (DDD).

DDD is really no different from Test-Driven Development, about which Rob Caron recently wrote, "According to Jonathan Cogley , Test-Driven Development  (TDD) is gaining in popularity . James Newkirk , Peter Provost and Brian Button are working on a new TDD example named Bookmark Collection." In fact, I believe that DDD is perfectly congruent with the precepts of TDD.

Anticipated Benefits

  • drastically lower documentation and localization costs.
  • the ability to simul-ship EN-glish and all other language versions of Visual Studio
  • nominally lower test costs (many test cases would be pre-written by writers)
  • greater cross-product consistency
  • greater developmental productivity...no, really.

Anticipated Costs

  • pedantic, predictable documentation that explains how to do things but not why you should do them one way or another.
  • writers would have to be more technical and experienced.
  • writers would be less productive since they would be involved in more design discussions, at least in theory.
  • lower quality specs: PMs would probably shift responsibility to documentation teams.

Comments

  • Anonymous
    September 15, 2004
    This type of DDD was standard practice for the "core" of a complex commercial graphics system I worked on. The primary benefit: overengineering and complexity were reduced. As soon as an API something became difficult to document, we realized it was probably not such a great idea, and needed to be rethought.

  • Anonymous
    September 15, 2004
    Hate to say it but I have been using this technique for program writing for some time. At least I have a label for it now, though. What I do is write my comments first about the method, class, etc before i write it so I can get a better idea of what it is supposed to do. Also as I write the method I change the comments accordingly as well.

    It is certainly a great idea.

  • Anonymous
    September 15, 2004
    The comment has been removed

  • Anonymous
    September 16, 2004
    The comment has been removed

  • Anonymous
    October 08, 2004
    DDD sounds more like Use Case Analysis. The more things change, the more they stay the same.

  • Anonymous
    August 18, 2005
    News on every hour. http://www.bignews.com

  • Anonymous
    March 19, 2006
    Very nice and informative website.

  • Anonymous
    April 29, 2006
    Very nice website with a lot of informative response from members

  • Anonymous
    June 02, 2006
    i like your website very much but please do get us more information about it

  • Anonymous
    August 22, 2006
    Very nice blog. I read it every day.

  • Anonymous
    September 03, 2006
    I'm impressed this site. You can be impressed also when you visit my. <a href="http://www.agnula.org/Members/carinsurance/car-insurance" title="Car insurance online quote">Car insurance online quote</a>

  • Anonymous
    November 23, 2006
    Great post. But: I think DDD is different from TDD. TDD is about "what exactly", and a little "how". DDD is - or should be - about "why and how". In my experience, you get the best results from combining both. That is what I do on my latest project with the help of a tool I wrote, JCite. It lets me cite example snippets from actual use-case API test code into the docs. An extension I have not implemented yet will even alert me when cited examples have changed so I can review the docs around them. http://arrenbrecht.ch/jcite/

  • Anonymous
    November 23, 2006
    > "pedantic, predictable documentation that explains how to do things but not why you should do them one way or another." Hmm. No methodology is ever going to make people produce good results when they are not focused on the real goals of the project. In this case, if people are not focused on delivering a great product with great usabilty and learnability, but rather of getting the daily chore over with, DDD will obviously not work. To explain well, you have to care about your audience, not your own agenda. Same goes for designing an API well.

  • Anonymous
    May 29, 2009
    PingBack from http://paidsurveyshub.info/story.php?title=korby-parnell-s-social-software-wunderkammer-documentation-driven

  • Anonymous
    June 16, 2009
    PingBack from http://lowcostcarinsurances.info/story.php?id=1109

  • Anonymous
    June 18, 2009
    PingBack from http://thestoragebench.info/story.php?id=1960