Documentation-Driven Development

re: Documentation-Driven Development

Frank Hileman — Wed, 15 Sep 2004 19:31:00 GMT

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.

RE: Documentation-Driven Development

rcallaby@earthlink.net (Richard Callaby) — Thu, 16 Sep 2004 02:45:00 GMT

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.

re: Documentation-Driven Development

Korby Parnell — Thu, 16 Sep 2004 04:00:00 GMT

Frank,
I wish I had a photograph of the PM who then owned the Solution Explorer window in Visual Studio when I presented for tech review a 6-page help topic (a whitepaper, really) that explained why dragging and dropping any file FROM a C++ project TO a VB project occasioned a different result (copy file) than dragging that same file FROM the VB project TO the C++ project (create reference).

The PM leaned back and said, "Duuude, this is just the tip [long pause] of the iceberg." And several seconds later, "This design is waaaaay [long pause] too complicated."

Of course, both Visual Studio .NET 2002 and 2003 shipped like that. The PM fought to unify the project item storage models for the disparate language projects in VS.NET 2002 and 2003 until he left the company a year ago. [And today? Today, he sent his super-smart daughter off to a new school she doesn't really like and paid an arborist an ungodly sum of money to try to salvage some great trees on the property upon which his newly-purchased home sits.]

I recently learned that it is very *likely* that these project item models will converge in VS2005, rendering what remains of my hideous conceptual topic defunct, and thankfully so.

That fact inspires me to continue to create great help content that both informs users of potential pitfalls and informs the feature designers and developers of potentially unnecessary complexity in Microsoft's tools for professional software developers like yourself.

I wholeheartedly embrace the truth of your elegant statement:
"As soon as an API [or] something became difficult too document, we realized it was probably not such a great idea, and needed to be rethought."

To put it another way: good requires explanation but great is completely self-documenting.

++++++++++++++++++
Richard,
I'm thrilled to provide a label for your time-honored development technique. Every idea is a meme, right.

It seems that putting a name to a thing or idea is one of my great talents in life. Too bad I'm not compensated for doing so. That being said, I did recently run afoul of the naming gods by mistakenly giving my daughter a name which, when pronounced a certain way, means something really bad in Persian.

Daughter Best Practice #1: 'When snowboarding in Iran, pronounce thy name Key-Era'! :-)

If you read this comment, perhaps you can add another comment which points us to sites or books that inspired you to adopt DDD techniques in the first place?

New Team System Stuff - 2004-09-15

Rob Caron's Blog — Thu, 16 Sep 2004 12:27:00 GMT

re: Documentation-Driven Development

Frank Hileman — Thu, 16 Sep 2004 15:36:00 GMT

I can't point to a book (we began working this way in the early 90s). Here is why we adopted this type of DDD:

When release-time came around every 3-6 months, we would look for the documentation for each new enhancement to the API. Supposedly, each enhancement had been thought out and designed. But the developers dragged their feet on the documentation. Each developer was responsible for the rough draft of the API documentation, and I (lead dev) was responsible for cleaning them up.

During the "doc phase", we often found the documentation process finding design problems or unnecessary complexity, that we just hadn't thought of, until we looked at the API from a "documenter's" point of view. The documenter's point of view precisely pinpoints communication problems and complexity. If something was hard to document, it was hard to use as well.

We often delayed releases just so we could address these problems, tweaking the public API. The documentation process thus became long and unpredictable, making release scheduling very difficult.

So we said, no more requirement specifications. That will not be needed. Instead, write the end-user documentation, before you even start the high level design. No work on any code (except perf tests) or design documents until the first draft of the end-user documentation is written. When that is done, and reviewed, we could be sure we had a good design from the user's perspective, as well as a fairly good spec for implementation.

Amazingly, the developers, who had all been through the previous painful "documentation phase", generally liked this approach, even if they were not good writers. They always had someone to help with the writing part (me). They recognized the value in this approach, and they were able to get that phase out of the way while the subject was fresh in their minds.

re: Documentation-Driven Development

Barry Gervin — Fri, 08 Oct 2004 21:01:00 GMT

DDD sounds more like Use Case Analysis. The more things change, the more they stay the same.

exciting

marria — Fri, 19 Aug 2005 05:45:07 GMT

News on every hour. http://www.bignews.com

re: Documentation-Driven Development

Payday Loan — Sun, 19 Mar 2006 18:54:48 GMT

Very nice and informative website.

re: Documentation-Driven Development

Katrina — Sat, 29 Apr 2006 15:09:48 GMT

Very nice website with a lot of informative response from members

re: Documentation-Driven Development

buy xanax — Sat, 03 Jun 2006 03:35:05 GMT

i like your website very much but please do get us more information about it

re: Documentation-Driven Development

Vlad — Wed, 23 Aug 2006 03:16:41 GMT

Very nice blog. I read it every day.

re: Documentation-Driven Development

insurance — Mon, 04 Sep 2006 14:30:51 GMT

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>

re: Documentation-Driven Development

Peter Arrenbrecht — Fri, 24 Nov 2006 10:59:14 GMT

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/

re: Documentation-Driven Development

Peter Arrenbrecht — Fri, 24 Nov 2006 11:03:47 GMT

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

Korby Parnell s Social Software Wunderkammer Documentation Driven | Paid Surveys

Korby Parnell s Social Software Wunderkammer Documentation Driven | Paid Surveys — Sat, 30 May 2009 01:22:33 GMT

PingBack from http://paidsurveyshub.info/story.php?title=korby-parnell-s-social-software-wunderkammer-documentation-driven

Korby Parnell s Social Software Wunderkammer Documentation Driven | low cost car insurance

Wed, 17 Jun 2009 07:24:09 GMT

PingBack from http://lowcostcarinsurances.info/story.php?id=1109

Korby Parnell s Social Software Wunderkammer Documentation Driven | storage bench

Fri, 19 Jun 2009 10:45:05 GMT

PingBack from http://thestoragebench.info/story.php?id=1960