When is a good time to document software?

Everyone knows about the benefits of having documentation. What is harder to agree on is when is a good time to produce it.

A good development cycle should always have its phase of documenting for the new features and the new behaviors to be expected. But, if it’s not your case, there are two other very good moments for documenting.

1. When a new employee joins the team

When someone joins the team, team members have to spend time with that person to teach him about the various applications at work. That can be done purely vocally, but that would be wasting a golden opportunity to create support for your teaching: documents.

Start documenting what you know you will have to teach. If documentation already exists, update it. Then, hand it over to the newcomer. Whatever question he may have, improve your documentation by answering in it.

2. When someone leaves for vacations or for good

It’s the opposite of the previous case. Rather than having a new team member, you are losing one temporarily or permanently. Someone will have to cover for the leaver. You can, again, proceed to knowledge transfer verbally or via documentation.

Create or update the relevant documentation and have the same back and forth process of the previous method. If the person is leaving for good, this is even more crucial.

Pros and cons

The pros and cons of these two scenarios are the opposite. If you gain a new team member, putting him in front of a screen and asking him to read the documentation might not be the best way to integrate him to the team since it lowers the interactions with others. However, since the person is new, he knows nothing and hence should ask way more questions than someone having context. For the other scenario, you don’t have to worry about team integration, but since the replacement might have way more context than a newcomer, he will ask less questions, making this process produce way less detailed documentation.

Bonus: The “Enterprise Flight Manual” used for this post featured image is available here.

Leave a Reply