[prosunpraiser]

In enterprise where there is poor documentation and lots of tribal knowledge, noting down just those 2 lines for every new info is a quick way to break down knowledge gaps created by just that.

It is exactly due to such disdain for documentation that most people find it hard to navigate large codebases. Documentation is not just for noting things down pedantically but also a thinking tool and a temporary thought buffer.

And no one pushes code to production to validate assumptions. Not if you have 100 clients and you are not doing CD.

[yazaddaruvala]

> And no one pushes code to production to validate assumptions.

I always have, with the rare issue occurring and by and large rewarded for it.

> Documentation is not just for noting things down pedantically but also a thinking tool and a temporary thought buffer.

Sure, but why not treat your codebase as a temporary thought buffer? I do, and it’s consistently worked and improved every system I’ve worked with. No teammate has ever complained about this strategy. If anything it’s typically adopted by teammates.

eg “oh this list is never modified” rather than taking a 2 line note, I’ll push a code change to use an ImmutableList.

The knowledge is now documented, enforced by the compiler/code reviews if the type changes people talk about it, and allows me to keep improving that part of the code base months later without code conflicts or needing to re-make my changes from a notes file.

1-2 line reactors - exclusively better than 1-2 line notes. This scales to any number of lines where the size of the note is equivalent to the size of the possible code change.

Meanwhile, please do take notes and document when it’s at least 10x shorter to grok than the current code or possible code change.