Writing Design Documents

Scott H has a great article on the importance of writing good design documents. As someone who’s spent the better part of his life documenting software, I can relate to this really well.

A design document is a way for you to communicate to others what your design decisions are and why your decisions are good decisions….The biggest factor that determines if your design document is good is whether or not it clearly explains your intentions.

I actually like that article because it dwells on the fundamentals starting right at what is good design.

A design will typically be considered good if it fulfills the requirements in a meaningful way. If any aspect of the design cannot be justified, then it is probably worth reevaluating.

Scott also backs up his case with a sample illustration of how you typically need to write a design document. And he says nothing fancy like UML or elaborate flow diagrams and the like.

Read it in full.

About On Writing Well

This blog owes its title and existence to the book on writing well (trillions of thanks to the inimitable MadMan for recommending it). My earlier blog was born with several deformities and died at childbirth, and I’m hoping this one will survive.

All for now.