DEV Community

loading...

Discussion on: The Bus Factor

Collapse
courier10pt profile image
Bob van Hoove

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 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.

Collapse
lukebearl profile image
Luke Bearl Author

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).

Collapse
einenlum profile image
Yann Rabiller

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 :)

Thread Thread
lukebearl profile image
Luke Bearl Author

Thanks! That's a fantastic idea and one I'll definitely bring up with my team.

Collapse
courier10pt profile image
Bob van Hoove • Edited

I think that README suggestion 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.

Thread Thread
lukebearl profile image
Luke Bearl Author

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.