Agile — Working software OVER comprehensive documentation, but no excuses after the software is working

Yes, the Agile Development Manifesto has one item that states the following:

“Working software over comprehensive documentation”

I am all for getting the software working and dealing with the issues without distracting the team with any unnecessary steps.

At the same time, I am also not a big a fan of long documentation even when you have time for documenting. Documentation is as good as it will be consumed. If nobody is consuming it because of its complexity and length, then something has to be done about it.

Single-page documents are ultimately what you should strive for. That one page should contain the overall design and concepts and also directional information which really points you to for example: a Git repo, a piece of code, or a working software that you can use to understand it, and …etc. If you start with the high-level overview and some direction, the low-level details can always be figured out if you know where to look.

This brings me back to the concept of working software and documentation. Let’s assume you and your team had some chaotic times to get the software working and you were the only person who knew how to do certain things and everybody was waiting on you to complete those tasks before other tasks could be worked on. There are two things that should be learned from this:

• After chaotic period is over and you have a working software, you need to document what you know and set up meetings with your teammates to share that knowledge.
• Your manager should be noticing these situations and recognizing that documentation is needed in order to prevent bottlenecks in the process of getting the crucial steps in the project.

Software engineering is an art of programming and everything else that comes along with it in order to get the software successfully delivered to production. There are three types of things regarding which your teammates or other teams could come to you asking for help:

1. Pure information sharing: For you to share information or repeatable instructions how something is done.
2. Opinion: For you to provide opinions how something could be designed or implemented.
3. Advice seeking: For you to share an advice on how something should be designed or implemented.

As professionals in the software engineering field, we should be spending more and more time on items #2 and #3 and less should be spent on item #1 which is mostly repeatable and something that can be easily documented.

When you read this article, ask yourself:

• Is there something that I only know and it is a repeatable process? If the answer to that question is YES, then please spend a bit of time just preparing a single-page high-level document with directions on how others can find low-level information. Approach your manager and share this with them and recommend further steps to share this with teammates formally or informally; sometimes simple and short videos can do wonders.

Thank you for reading. Please follow me here on http://medium.com/@almirx101

I also have some YouTube videos about software engineering at: http://www.YouTube.com/almirx101

Almir Mustafic