Today I created an Angular best practices guide at work and created a repo in our official Github repo and shared it in our Slack channel and asked people to collaborate and create docs and guides for other tech stacks as well.

One of our teammates quickly shared a repo that dates even before I joined here that has best practices guide for some other tech. She asked if we can keep either one of these repositories. I merged both and created a unified repository. In my defense, I was never aware that the best practices guide repo exists already.

But this kept me thinking, she is fairly new to the organization than me but was aware of an old repo. I understood that not just writing documentation at random places and hoping people will pick them up will never work well. Documenting is the easier part. Keeping them up to date and discoverable for others is the real challenge.

It has to be instilled in the team culture, that documentation is available and it should be used and updated. If docs are available but outdated, people will stop using them. If people stopped using the docs, they will get even more outdated with no relationship to reality. This is a vicious cycle. Eventually, your documents and any past efforts you put into them will go to waste.

To keep this from happening, we should try the following.

1. Write docs.

2. Redirect people to docs.

3. Keep them public, discoverable and searchable.

4. Be a Scout, Leave the doc better than you found it.

5. Ensure that documentation is being written and used at all levels of the team/org.

Documentation when done right can do wonders for a team and saves a lot of engineering time. But keeping working documentation is a really a herculean task, that no one individual could make happen.