Golden Rule of Documenting Software Design

In the Next Programming Skill You Should Learn, Scott Hackett talks about the ability to communicate well, especially in writing. I totally agree. The post is certainly worth a read.

An unexpected bonus in this post is Scott’s tips on the golden rule of documenting software design.

The golden rule of documenting software design

Try to document whatever you are working on. It doesn’t have to be the worlds most perfect UML and you don’t need an expensive tool to do it. In fact, Wordpad and Paint are sufficient, and don’t tell me you don’t have those. Write in a way that best expresses your intent and your thought process in coming to the design decisions you did. I have a golden rule of documenting software design:

Describe your design to others as you would have others describe their design to you.

When you spend the time to do this, you’ll find that many benefits will follow. You’ll get feedback from others that may have tried to solve a similar problem and have insight you may not have thought of. You’ll leave a clear trail to follow for those that work on the code after you. Most importantly, you’ll shed light on your work, which everyone who depends on your work will appreciate. Even if no one else reads what you write, you’ll still have worked through problems in your head that can only lead to better design in the long run. There is no downside to documenting your designs.

One of the experiments I am conducting with a set of interns is to make them write a LearnLog and ProjectLog – just a few bullets or short sentences. We do this in a wiki so that every one in the project has access to it.  It is also one of the easiest and most effective ways to communicate asynchronously with the team.

In the Project Log, they are supposed to write the following:

  • Design decisions
  • Decision to use libraries/tools and why
  • Problem areas and stumbling blocks and how they solved it
  • A list of links to the resources they used

It is still an uphill battle but we are getting better gradually.

3 thoughts on “Golden Rule of Documenting Software Design

Comments are closed.