Article Blog Image

Agile doesn't exclude software design diagrams

The truth about documentation and Agile

In past, managers had amazing skills to push us, developers, with words: “You have to finish it before the deadline! We already announced the release date.”

Obviously, this was creating a lot of conflicts between/inside the teams and no one would naturally think about taking a marker and start actually thinking through the solutions by sketching system, software diagrams on a whiteboard. “Let’s code people! Hurry up!”

This phenomenon got even worst in last few years. The bold word “deadline” was replaced with a way more sophisticated version: “Scrum sprint”.

Managers very subtly changed the dynamics of the whole game by exploiting the Agile philosophy so they don’t look like the bad guys with words:

You have to finish it before the end of the sprint!

You have put the tasks to the sprint yourself! We already announced the release date, YOU gave us, even though we know developers always underestimate!”

I have to admit. Fantastic devil move. Subtle smile. Shame it will backfire to every greedy manager face once the developers will communicate that they need double of the time to fix the new and already broken software that got out of control, original plan.

There are very few good, experienced managers who understand that short-term winnings will cause long-term troubles.

And we, developers, carry 50% of the guilt for the conflicts and the broken released software ourselves! It’s also our fault that we get pushed around and underestimate tasks without including the necessary time for documentation and software design.

Remember, developers, product, all stakeholders must transparently, respectfully, professionally work hand in hand in order to deliver software that will make users happy and the company successful!

Now. Let’s take a deep breath to fully concentrate on the following sentence.

The philosophy of Agile is to do the least amount of something and no more for a given situation.

Evil Misconception

There is no need for documentation and software diagrams.

Real true:

Design the diagram before jumping into the code and write the documentation for the parts that really matter if that’s what is required to move forward, to deliver a solid product.”

If every reader will remember at least this statement from all of the articles I have/will publish or the course I created:

  • The world will be a better place. (Seriously, unicorns and rainbows level)
  • The quality of your work will skyrocket as you will write better software
  • The possibility of the plan aligned by all stakeholders getting out of hand will be reduced
  • Better software => Better user experience => More user engagement => Happy team


Given that Agile statement and the fact I am actually a big fan of Agile and the Lean process.

If you just woke up and you want to validate your new amazing business idea then, of course, don’t waste time on some documentation and diagrams. There is around 95% chance that your idea will fail anyway. Just get it as fast as you can in front of your target audience to collect the necessary feedback.

On the other hand, if you are working on a core product for your company and you are experiencing some performance bottlenecks due to the product popularity and you need to come up with a new system that will handle the traffic then your manager actually EXPECTS from you to come up with a SOLID plan and to spend time on planning, diagrams, and documentation!

Include documentation, software diagrams tasks in your sprint!

Make a sprint only for diagrams and benchmarks if necessary!

Writing documentation and designing diagrams for parts of the software that REALLY MATTERS is perfectly compatible with Agile methodologies and is your not written responsibility to do it!

Please. Spread the word about it so we bring back the real software culture of quality.

Make sure when you are estimating with your team the incoming tasks to consider the time necessary (IF NECESSARY) for documentation and software design.

Start writing S.O.L.I.D, designed, documented, agile compatible software.


Your feedback (if constructive) is important to me! Feel free to open an issue or create directly a PR with changes if you wish to help me and the readers to grow.

Provide feedback