In span of 6 months since I joined this large financial organization, I’ve created close to 30 wiki pages on internal Confluence. They span wide range of topics related to our application; from server/environment details to code walk-throughs to Jenkins Pipelines set-ups.
I have been reflecting on effects of this - sometimes excessive - habit of documentation, on my team. More so because there is almost a disdain amongst developers towards documentation (similar to testing).
Let me elaborate on some of the benefits I have seen.
Reduced dependency
In large organizations, projects/applications span multiple years. During this time, there is lot of churn in the team. People who stay the longest in the team accumulate lot of application/domain specific knowledge. Depending on the culture, this knowledge is withheld to gain unfair advantage.
Documentation takes power away from an individual and gives it to the team.
This reduces dependency on a single individual. It comes handy if people leave or when someone is on vacation or out sick.
Culture changes
This encourages a culture of transparency. With information freely available across the team, the discussions no longer focus on “what”. Instead they are around how to improve the state of things.
Documentation is not a silver bullet for better culture, though teams with better culture tend to share more.
Faster onboarding
Documenting application architecture, external dependencies, code flows, etc. vastly improves the onboarding experience. New team members are typically shy. They tend to ask less questions, afraid of coming off as silly. This accessibility of application know-how tends to equalize their importance in the team, in addition to improving their confidence.
Transcends knowledge across teams
In large enterprises there are many proprietary systems. Knowledge of these systems - flows, setups, approvals etc. requires lot of coordination across teams (sometimes across time-zones). Having a organization wide wiki has helped us so much, in being more efficient. Case in point, our sister team was able to setup continuous integration just based on the wiki page we had detailing the steps.
Different way of teaching
Knowledge sharing sessions are excellent ways to share knowledge. But each person has a different level of existing understanding of the topic, and each person learns at a different pace. Having a recorded session (yes, this is also called documenting) helps getting well versed with the topic at their own convenience.
Do it now. Thank me later.
- But its time consuming - I hear you. I agree with you. The ROI (Return on investment) though is many-fold.
- But our team is agile - ‘Being agile’ is more about self-organizing and self-adapting as a team. Documentation helps with that.
- But its a prevalent culture - All it takes is one team member to start doing it, good things will follow. Trust me.
My team has been very happy given the ample evidence of positive affects documentation has had. It has encouraged some of my colleagues to follow suit and I couldn’t be happier.
Tags: