Writing Design Documents

September 27, 2007

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

September 11, 2007

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.

Another Office Woe

August 20, 2007

Joel hits it well.

I bought a retail copy of Office 2007 today…. but I simply could not figure out how to open the bizarre new packaging… It seems like even rudimentary usability testing would have revealed the problem. A box that many people can’t figure out how to open without a Google search is an unusually pathetic failure of design.

Amazingly ROTFL stuff. Microsoft may as well open a new tech support website/help desk to take calls from irate customers who can’t get a box open. As a technical writer, I advocate Microsoft to attach a user manual/cue card that gives instruction on how to open the box.

I guess these giant-sized companies prohibit commonsense directly in proportion to the profits they rake in.

PS: I’m using Office 2007 but like millions of others, am unable find ONE compelling reason why I upgraded. The benefits of hindsight 🙂

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.