Documentation-Driven Development

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.

Published 15 September 04 08:18 by KorbyP

Filed under: Programming, Documentation

Comment Notification

If you would like to receive an email when updates are made to this post, please register here

Subscribe to this post's comments using RSS

Comments

# Frank Hileman said on September 15, 2004 12:31 PM:

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.

# rcallaby@earthlink.net (Richard Callaby) said on September 15, 2004 7:45 PM:

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.

# Korby Parnell said on September 15, 2004 9:00 PM:

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?

# Rob Caron's Blog said on September 16, 2004 5:27 AM:

# Frank Hileman said on September 16, 2004 8:36 AM:

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.

# Barry Gervin said on October 8, 2004 2:01 PM:

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

# marria said on August 18, 2005 10:45 PM:

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

# Payday Loan said on March 19, 2006 11:54 AM:

Very nice and informative website.

# Katrina said on April 29, 2006 8:09 AM:

Very nice website with a lot of informative response from members

# buy xanax said on June 2, 2006 8:35 PM:

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

# Vlad said on August 22, 2006 8:16 PM:

Very nice blog. I read it every day.

# insurance said on September 4, 2006 7:30 AM:

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>

# Peter Arrenbrecht said on November 24, 2006 2:59 AM:

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/

# Peter Arrenbrecht said on November 24, 2006 3:03 AM:

> "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 said on May 29, 2009 6:22 PM: