architectureumldocumentationwikireadme

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


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.


Solution

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