3 ms·
> I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons: I have a sma
by chupchap 5y ago
> I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons:
I have a small disagreement on that. I always feel documentation should be outside of code as it might need to be reviewed by people who do not have access access to the code base. Then there are also the "Why are we doing this" part of documentation that is difficult to mark out in code. Documenting in code is great for addressing "how are we doing this" part IMO.
- simonw 5y agoThe docs may live in the repo but they should definitely be published somewhere that non-GitHub users in the organization can view. The higher level strategic stuff can absolutely live elsewhere - in my experience Google Docs or some kind of company-wide wiki often come into play here.
- chupchap 5y agoI was thinking more of an enterprise situation where multiple systems might be working together as part of a process. The code for each system might be in different repos in which case the documentation would also be broken. In such a context having the unit level documentation in the repo makes sense, but the overarching process documentation that is constantly evolving and referenced by multiple teams cannot be part of this repo.
- zie 5y agoI assume the OP meant, or at least how I took it and implement it, it can be in a dir called docs/ off the root of the tree. It doesn't have to be literally scattered about in the actual source, just in the same repo. Though there are reasons to do both(some docs from the source itself, and some from docs/) but that's a different debate.