Item — HN Reader

Most modern software shops don't document at all. They would definitely benefit from writing down a problem statement and description of the solution so that everyone is on the same page.

Documenting doesn't have to mean design-first development, it's a way to make sure you're working the right problems and building the desired solutions before you waste your time writing code.

1 comments

I've tried to force myself to write something in English before coding, and... it's not 100% followed, but it's often helped. Sometimes I'm not even prescribing the full 'solution', but it's a sketch of the pros/cons of a couple approaches. This can help me remind myself later of why a particular option was chosen, even if it turns out to be bad.

I can't say if anyone else who looks at the code ever also reads what I've written - it seems that generally they don't (even though I announce it and it's in the commit activity stream and PRs).