Re:Ask HN: What's the best way to manage institutional knowl...
by throwawayacc2 on Sunday September 11, 2022 @03:59PM
(#32802737)
I found well written and maintained readme files to be useful. That and redundancy in terms of people who know the code base.
The best readme files write in english what the mode does, a sort of heat-map of the code ( often some parts are more used then others ) and pitfalls.
I’m also a big fan of short and succinct comments in appropriate places. I once broke production because I saw a private key being written to kafka. It felt odd so I removed that. Turns out something was reading that private key. There’s now a comment saying “When checkin data, double check this other module”
But the best thing is to have shared knowledge. I don’t think it’s useful or practical for regular engineers to know everything but the tech leads should be able to provide guidance across the larger cod base.
The best readme files write in english what the mode does, a sort of heat-map of the code ( often some parts are more used then others ) and pitfalls.
I’m also a big fan of short and succinct comments in appropriate places. I once broke production because I saw a private key being written to kafka. It felt odd so I removed that. Turns out something was reading that private key. There’s now a comment saying “When checkin data, double check this other module”
But the best thing is to have shared knowledge. I don’t think it’s useful or practical for regular engineers to know everything but the tech leads should be able to provide guidance across the larger cod base.