The "explanation of its components" is the problem: someone needs to do it. Open source projects don't have an employee's first day, so they don't have this introduction.

They're not good if you don't have a sea of time, though. (An employee is expected to take a few weeks before getting anything done on their own.) I'm a security consultant, so we get to see a brand new one of these every two weeks and the problem with these explanations is that they are ad-hoc, unstructured, and mention lots of irrelevant details because the speaker has the curse of knowledge.

Perhaps someone new to the repository should write this thing once, after which it can just be maintained. Second best is to just have anybody write it down, taking a minute to think about what goes in there and what doesn't rather than doing it always on the fly, because as the author says:

> 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.

> The "explanation of its components" is the problem: someone needs to do it. Open source projects don't have an employee's first day, so they don't have this introduction.

Also a problem in my day $JOB the previous rockstar devs didn’t provide anything like this so it’s not a n open source thing it’s a the-code-are-the-docs mentality.