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