Where to place summary & UML diagrams in a GitHub repository?

Question

The README.md files of many popular GitHub repositories usually provides a high-level overview of the application's purpose and its main features, with usage instructions (e.g. how to compile & run).

What I want to do is explain the architectural style used in the application, the use cases, its trade-offs and such? I thought I'd throw in some UML diagrams too, in order to anticipate possible issues that new contributors may experience and to be a reference used during their onboarding phase.

Should I put all of this inside the repository's Wiki, a separate blog or just some additional markdown files? Is there any consensus about how to do this? Or any example worth checking?

I've yet to decide an approach to the problem, I've tried writing some detailed instructions and an app overview in the README.md file but it was too long to be useful in just one file and felt out of place.

Answer 1

There is no broad consensus about documentation in repositories. However, there are some recommended practices:

• README.md is the entry point to the repository. While its content and focus are free, it should provide at least a hint about where to find the documentation for the developer and the structure of the repository.
• As a consequence, it doesn't matter where you put the documentation, since its entry point will be found in the readme.
• It is recommended to keep the technical/programming/architecture documentation in the same repository than the code, because 1) it evolves with the code; 2) it is the best way to ensure that those who need it, will find it.
• For architectural documentation there are some popular recommendations such as ADR. UML could go into same folder.
• If you generate UML schema and technical documentation from your code, you should consider having it in a separate folder, to avoid mincing generated file (automatically overwritten) with manually edited files.