dotNetDave Says… Documenting Software Projects

If you don’t document your project, then how can developers code it, QA test it and Tech Support assist users?

dotNetDave, November 2019

With so many software development methodologies out there, it’s important to remember to do proper architecture and document your project BEFORE coding begins. I’ve seen methodologies come and go and with some methodologies such as Agile, I’ve seen less and less documentation and sometimes, NO documentation.

While writing this article, Uncle Bob Martin tweeted this about Agile…


I agree with Bob 100%, but again in my experience, I don’t see Agile teams doing proper planning.

Whenever I’m in a meeting, talking about how important it is for the requirements and the design of the project to be documented, and I get push back, I then ask them…

  1. How are developers supposed to code the project without documentation?
  2. How is the QA team supposed to test the project without documentation?
  3. How is Tech Support supposed to assist users with issues without documentation?

When thinking about these questions, its best to answer them with the thought that anyone in the teams above is a new hire. Meaning, they don’t have a lot of domain knowledge of the type of projects the company or team writes. How would a new person on the team code, test or support the project without good documentation? This is even more important if your team hires contractors!

When I learned to program, we never wrote a line of code until the requirements and design documents were written and signed off by the stakeholders.  This is how the Waterfall methodology works.

The Cost of Not Creating Good Documentation

For some reason, many software team managers believe that if developers aren’t at their desk coding, they aren’t working. This can’t be further from the truth. Time spent coding should actually be a minor part of your job.

The cost of not having good documentation is very high. As you can see in the chart below from a study I read a long time ago, by the time coding begins, fixing an issue is ten times the cost than if it wasn’t resolved in the requirements phase and twice the cost if it wasn’t resolved in the design phase. By the time the user reports the issue, it’s over 150 times the cost to fix! Print this graphic and nail it to your manager’s door (if they have one)!

Röck Yoür Cöde with Defensive Programming-20161

Emails, group chats, Slack and more isn’t documentation! That is more information gathering. Documentation is writing it down in a document using Word. There are many templates out there on how to create great requirements and design documentation. I recommend you search online for the one that works best for your team. Good documentation will also help prevent “feature creep“.

Also, while writing this article, I saw Peter Ritchie Tweet this…


Without proper planning, teams will end up patching software over and over. The more that happens, it makes evolving the architecture almost impossible. Maybe that’s why so many teams, including at Microsoft, rewrite software, sometimes under a new name, since the original software is too hard to evolve.

Defensive Programming eBook@0,25xI do discuss this in my defensive programming session at conferences. To see where I will be presenting it, please go here: I also wrote more about this in my book Rock Your Code: Defensive Programming in Microsoft .NET.

How does your team produce documentation (if it does)? Please make a comment below.

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.