@brecht
One thing I’d like some feedback on is what people think about moving the docs into the main Blender repository.
For developer documentation, I’m very much in favor of moving them into the main Blender repo.
A recent case study of why I think that’s a good idea:
We recently merged hierarchical bone collections, which included plenty of Doxygen doc comments for functions, etc. But there is a higher-level design of how the hierarchy is laid out in memory and its invariants that didn’t have any obvious place to go. (It could have been a massive comment right smack in the middle of bArmature in DNA, but that didn’t seem appropriate.) Importantly, this higher-level design is just as relevant to understanding and working with the code as any of our Doxygen comments.
But because it’s not in the same repo, documenting this important aspect of the code became a separate step that we had to take note to do later. And in my experience, making documentation a separate step rather than intermixed with writing code makes it a lot less likely to happen.
Moreover, intermixing documenting with coding also significantly increases the chances that existing documentation is updated along with relevant code changes.
In short, I think that writing/maintaining code and writing/maintaining the documentation for that code (whether it be doc comments or higher-level design documentation) should be viewed as part of a single, continuous process. And it’s a lot easier to psychologically buy into that and make it a habit if the code and documentation are in the same repository.
I think the only thing I’m ambivalent about is including documentation that’s not directly related to the code base or Blender’s design. For example, although I view build instructions as directly relevant (if I clone a repo, I should be able to figure out how to build it from the contents in the repo itself), I do not view communication channels or organizational development processes as relevant.
@ZedDB
I think this will make PRs and commits a lot more noisy. Not just the amount but the content/discussions in the PRs as well.
I certainly understand the desire to avoid more noise in PR discussions. Particularly of the bikeshedding variety. And I agree that it’s even easier to bike shed prose than code. So I’m very sympathetic to your desire to avoid that.
However, I think it’s worth the benefits. Documentation is much less useful if it’s out of date or otherwise inaccurate. By allowing documentation changes to accompany code changes, we can more easily ensure that relevant documentation additions/updates actually get made, and double-check that they’re an accurate reflection of the code changes.
(I’m also just generally of the mind that code and its documentation are deeply interrelated, and should always accurately reflect each other. If they don’t, I view it as a kind of bug. (Edit: there are some situations where it makes sense for things to go temporarily out of sync–I phrased that too strongly.) So to me, ideally dev documentation changes should accompany code changes in a PR. But I won’t push that point.)