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.

Chuck those Plans

In a bold post, Shtikl argues in favour of chucking elaborate plans and instead, concentrate on problem-solving. As far as I could make out, the crux of his argument lies here:

Until you don’t have the skills to make an idea happen you are not in the place to make a plan.

To bolster this, he holds up the biographies of great achievers none of whom

…actually planned to accomplish what they did accomplish.

You might disagree with his piece in bits but it’s a nice tidbit for thought.