Five reasons to write documentation

on agile

"If it's not in writing, it didn't happen"

As Agile coach this is a common pattern when working with new teams: absent documentation. The reasons can vary from organisational issues, misunderstanding or even people underestimating their ability to write documentation.

People will find creative objections. They try to rationalize why documentation is not needed.

  • We work Agile
  • Everything changes too quickly
  • It's just a waist time
  • You can read the code/tests

Let me clear on this. These are NOT valid reasons to stop writing documentation.

Writing documentation ensures repeatable processes.

This ranges from business processes to technical and operational processes.

You can still work agile. You can still keep up in a fast and dynamic environment. Value is removing operational ambiguity. This can be done by writing a base process and incrementally review and improve.

Agility still needs stability in operations. Trust is built on stability. Repeatable process improves reliability.

Efficiency

"Talking is temporary. You can't "relisten" to something."

When you have clear documentation you company can scale. When hiring new employees they speedup faster. Also you're existing people don't need to spend additional time to assist them.

Building a knowledge base with troubleshooting documentation. Less time is spend solving the same problems. Now you can solve more problems in a shorter time

Clearly written process documentation is easier to automate in the future

Define goals

When you define a goal and document the steps to reach that goal. You make sure that everyone walks in the same direction.

People may even find ind a better or faster route to the goal. When they improve the documentation you'll get better at reaching your goals.

Mind readers don't exist!

Technical documentation explains your intent:

  • Why did you do what you did
  • Why is it like this
  • How did you want this to be implemented
  • Did your learn something
  • Common mistakes
  • Troubleshooting help

Documentation is a form of communication. In communication context is important. Dale H. Emery wrote a beautiful piece about this.

You’re a professional.

You care about people that come after you. You care about your team members.

Conclusion

It makes business sense. You cut costs due to increased efficiency. It will free up time to invest other work that creates more business value.