If you maintain an open-source project in the range of 10k-200k lines of code, I strongly encourage you to add an ARCHITECTURE document next to README and CONTRIBUTING. Before going into the details of why and how, I want to emphasize that this is not another “docs are good, write more docs” advice. I am pretty sloppy about documentation, and, e.g., I often use just “simplify” as a commit message. Nonetheless, I feel strongly about the issue, even to the point of pestering you :-)

The case for adding a document to a project's source code repository, telling the ones interested in the code how things fit together, and where to start looking for certain functionality.

view link