DEV Community

loading...

How do you document new "coding patterns" for your team?

tmr232 profile image Tamir Bahar ・1 min read

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?

Discussion (14)

pic
Editor guide
Collapse
ben profile image
Ben Halpern

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.

Collapse
tmr232 profile image
Tamir Bahar Author

Do you link to it from the code as well?

Collapse
ben profile image
Ben Halpern

I think we do in some places but not as a rule. Worth considering.

Thread Thread
tmr232 profile image
Tamir Bahar Author

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

Thread Thread
ben profile image
Ben Halpern

With the fear of adding too much complexity, seems like checking for dead links could probably be done via some sort of static analysis.

Thread Thread
tmr232 profile image
Tamir Bahar Author

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.

Thread Thread
ben profile image
Ben Halpern

Well I was thinking maybe the analyzer could find the links and try test them for 404s.

Thread Thread
tmr232 profile image
Tamir Bahar Author

But what do you do when you find them, if the link is already dead?

Thread Thread
ben profile image
Ben Halpern

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.

Collapse
stefandorresteijn profile image
Stefan Dorresteijn

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.

Collapse
andy profile image
Andy Zhao (he/him)

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

Collapse
purplebooth profile image
Billie

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.

Collapse
arj profile image
arj

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.

Collapse
justinctlam profile image
Justin Lam

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.