Ask HN: How to get a team to document essentials?
This makes sense in some ways, since some things are ephemeral and fade faster than the docs might live. However, I’d like to foster a culture of sharing essential knowledge.
For example, we have one person that manages the infrastructure. This person documents nothing, even when asked, and we end up in the dumps when things go wrong in their absence. Their code isn’t self-documenting either and the nature of our setup makes it hard to grok in a pinch.
Another example is projects with complexity, knowledge of which is essential to working on the project and may result in errors otherwise.
Knowledge right know is sparsely stored around in an unorganized way, and when anything is documented there is no attempt to keep it organized, so we ended up with a jumbled list of pages without much context or way to gain context.
One thing that’s mentioned is that mob programming helps remove the need for this, but I disagree.
With this, new hires can get up to speed more easily with documentation that covers the essentials.
I’m not talking about deep and extensive docs. I’m talking about docs with essential info to understand the project and be able to work on it.
Folks are resistant to document things so I’ve taken the role of sitting with them and having them run me through their work, and documenting what needs documenting, when it’s apparent that something should definitely be documented.
We’re already seeing problems where some essential piece of tribal knowledge was not shared and resulted in customer-facing problems, and this is only getting worse as we grow.
It’s also very hard to understand the history of a project and why certain decisions were made. Often, the original developer doesn’t remember.
Does anyone know of a good way to document and make readily available _essential_ knowledge, and allow for contribution in a low-friction way?
I say low friction because every extra step between putting you and words on a page reduces the likelihood that someone will document something that should be documented.
Notion seems a good option and I’ve made a small test site, which works well. Our current solution is not sustainable.
Do we have deeper issues here? If so, what are the issues that you identify and which solutions could you perhaps suggest?
Perhaps documenting in the manner I mention isn’t even a good idea. In that case, please also let me know why it isn’t and what we can do instead.
The more we grow, the bigger the issue of tribal knowledge of a few longer-term developers becomes.
I need to head to sleep now but will respond when I wake if there are any replies.
Thanks in advance for your time.