In my experience, a healthy level of knowledge sharing is one of the hardest things to achieve within a team. Especially if you start using 'unfamiliar' techniques or libraries.
I'm a fan of README files at the solution level, containing:
a brief description of the project
prerequisites
instructions on how to get the project running (if anything special)
information on how to deploy it / where it resides
With this information you can run the project and make a change. And when the time comes to make changes in the unfamiliar part you can learn it by copying and pasting from Stack Overflow :P
Wrapping up, README won't solve your 'bus-factor' problem but it's a cheap way to alleviate some of the pain.
README files are good, but they have the same issue as any other documentation: developers don't like updating (obviously there are exceptions to that generalization).
Overall wikis have been good. We use the full Atlassian Suite so Confluence interops with everything else. The big problem is that the wiki isn't linked to the code at all, so things can change and people always forget to update. The only real solution we've found is to try and be vigilant about Documentation. Since we do code review on all branches it might make sense to try and have the reviewers also catch any documentation updates that are required.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Thanks for posting. I'm familiar with the issue..
In my experience, a healthy level of knowledge sharing is one of the hardest things to achieve within a team. Especially if you start using 'unfamiliar' techniques or libraries.
I'm a fan of
READMEfiles at the solution level, containing:With this information you can run the project and make a change. And when the time comes to make changes in the unfamiliar part you can learn it by copying and pasting from Stack Overflow :P
Wrapping up,
READMEwon't solve your 'bus-factor' problem but it's a cheap way to alleviate some of the pain.README files are good, but they have the same issue as any other documentation: developers don't like updating (obviously there are exceptions to that generalization).
I wrote an article about how to make developers update frequently their documentation and how to detect regularly the bus factor.
Hope it can bring some new ideas :)
Thanks! That's a fantastic idea and one I'll definitely bring up with my team.
I think that
READMEsuggestion mostly stems from past annoyances with projects that make you figure it out all yourself :)You mentioned your experience with wikis. I wonder, how did that work out? Was it well adopted? What sort of information would you put in there?
For one thing I like that it's hypertext.
Overall wikis have been good. We use the full Atlassian Suite so Confluence interops with everything else. The big problem is that the wiki isn't linked to the code at all, so things can change and people always forget to update. The only real solution we've found is to try and be vigilant about Documentation. Since we do code review on all branches it might make sense to try and have the reviewers also catch any documentation updates that are required.