Locality of the information is important. People will see comments in the code. They may even bother to read a README.md dropped in the same folder as the file

Locality of the information is important. People will see comments in the code. They may even bother to read a README.md dropped in the same folder as the files they’re looking at. They probably won’t look in a docs/ folder in the root and they’re almost definitely not going to go search Confluence. Centralized documentation is great for high level information. “Here’s an overview of the water treatment system.” You know where I wanna see instructions for resetting the alarm after cleaning the filter? Beside the filter. Most of my “home documentation” is sharpied pieces of masking tape stuck around the place.