New language features and libraries often introduce new patterns into the code-base.
Learning those patterns then becomes essential to understanding the code and reasoning about it.
How do you document such patterns, for the benefit of your team-members?
For further actions, you may consider blocking this person and/or reporting abuse
Top comments (14)
We use our GitHub Wiki for this sort of thing. I wouldn't say it's a strongpoint necessarily and we don't always communicate important new pages well. Would love to hear what other folks are using.
Do you link to it from the code as well?
I think we do in some places but not as a rule. Worth considering.
I am somewhat worried about having dead-links in the code later. Documenting in same repo comes to mind, but then it is hard to refer to from other code...
With the fear of adding too much complexity, seems like checking for dead links could probably be done via some sort of static analysis.
That works when you modify the code, not when you rename your wiki pages...
I'll probably start documenting in a wiki and link to it. If I find any better ideas, I'll probably write about them on this site.
Well I was thinking maybe the analyzer could find the links and try test them for 404s.
But what do you do when you find them, if the link is already dead?
Well at that point I feel like it's like a failed test. Somebody has to go deal with it and replace the link or remove it. The analyzer's job was only to flag it. This isn't to say that this marries well with the GitHub Wiki as the destination, but that's how these two things would combine.
Another possibility altogether, could be to have documentation actually hosted within code or something and you could verify presence and possible correction the way you would test code. Given sufficient abstraction, this is not too different from verifying 404s though I think.
We tried a couple methods. Confluence was too scattered (really dislike it). We did it per project for a while (readme file with patterns and styles, alongside our ESLint rules) and then moved everything to Github Wiki to make sure all projects worked the same.
+1 to Confluence being too scattered. I've never used it for technical write ups, but I basically just needed to bookmark every single page I needed.
I use the $CANONICAL_DATA_STORE for the company (current project it's the README.md) including a link to where good examples can be found. This should be a link to one of the tools repositories or documentation pages.
If the tool is going to touched a lot I'll create a 30min talk on the tool and give examples on how to use it, where I explain good ways to use it, and importantly if I haven't covered something, where others can look for other examples.
To re-enforce this I ensure that in the code I have a "gold standard" example and I make sure I state, this is your go-to example for this tool. Then during your code review making sure that you only allow very good usages (particularly at first).
This way you cover multiple learning styles.
Again this is only for the most important tools, for most stuff simply a gold standard and a double check in the code review.
We do mainly "document" or rather train the team by the code reviews and a weekly training-like meeting where code smells and new patterns are discussed. Works quite good so far.
My experience is that documentation doesn't help too much in this case because if people don't know them by heart then they don't apply them.
We create slides though, where we explain new things which they can refer to.
If it is just language styles and patterns using a linting software is invaluable. Better to have a compiler catch those issues for the developer.
For other domain specific patterns, code review or constant education/reminders are the best way. I found that having a "document" somewhere is only helpful as a reference but people generally don't remember to read it or remember what was written on it. As for where we store that document, some ideas are OneNote or a markdown in your git repo.