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.
- No location available
- documentation, open source,

(highlight:: One of the lessons I’ve learned is that the biggest difference between an occasional contributor and a core developer lies in the knowledge about the physical architecture of the project.
Roughly, it takes 2x more time to write a patch if you are unfamiliar with the project, but it takes 10x more time to figure out where you should change the code.)
- No location available
-

(highlight:: As the name suggests, this file should describe the high-level architecture of the project.
Keep it short: every recurring contributor will have to read it.
Additionally, the shorter it is, the less likely it will be invalidated by some future change.
This is the main rule of thumb for ARCHITECTURE — only specify things that are unlikely to frequently change.
Don’t try to keep it synchronized with code.
Instead, revisit it a couple of times a year.)
- No location available
-

(highlight:: The codemap should answer “where’s the thing that does X?”.
It should also answer “what does the thing that I am looking at do?”.
Avoid going into details of how each module works, pull this into separate documents or (better) inline documentation.
A codemap is a map of a country, not an atlas of maps of its states.)
- No location available
-