github存储库的文件通常提供有关应用程序目的及其主要功能的高级概述，并提供了使用说明（例如如何编译＆运行）。
我想做的是解释应用程序中使用的建筑风格，用例，其权衡等？我以为我也会投入一些图表，以期预测新贡献者可能会遇到的可能问题并成为他们入职阶段使用的参考。 我应该把所有这些都放入存储库的Wiki，一个单独的博客或其他一些额外的Markdown文件中吗？还是值得检查的例子？ 我尚未决定解决这个问题的方法，我尝试在
README.md文件中编写一些详细说明和一个应用程序概述，但是在一个文件中只能有用并感到不合时宜。
关于存储库中的文档没有广泛的共识。但是，有一些建议的做法：
ReadMe.md是存储库的入口点。尽管其内容和焦点是免费的，但它应该至少提供有关在哪里找到开发人员和存储库结构的文档的提示。 结果是，将文档放置在何处都没关系，因为它的切入点会在readme中找到。 建议将技术/编程/架构文档保留在相同的存储库中，因为1）随着代码的发展； 2）这是确保需要它的人找到它的最佳方法。对于建筑文档，有一些流行的建议，例如
adr。 UML可以进入同一文件夹。 如果您从代码中生成UML模式和技术文档，则应考虑将其放在单独的文件夹中，以避免使用手动编辑的文件分割生成的文件（自动覆盖）。