I like the idea of putting everything in the same repository. I think it’s just way simpler (and things are already complicated enough).
Repository size would be an issue if we host all images and movies in the repo. Look at the ProjectWeek repo which is already almost half a gig. At the same time I’d like a seamless process for adding media to the documentation.
Access control, actually sounds easier if we make all documentation changes pull requests.
Videos would probably not be updated that frequently, could be very big, and mostly accessed online (you could not print, would not want to bundle them with the manual anyway), so I think we should just add youtube links for videos (as it is done in Blender manual). We can enforce reduced-size screenshots and images through code reviews.
@jcfr It seems that we all lean towards trying to host documentation in the same repository and branch as the source code. If you agree, too, then it would be great if you could merge rst… branch to master and change readthedocs settings to generate documentation from master branch.
If we make the merge and finally have a “live” rst documentation (the current one I consider kindof dormant), then I volunteer to migrate some of the most important pages to rst.
It is live (updated automatically within minutes) but generated from rst-user-and-dev-guide branch. You can start adding content in that branch.
Yes, thanks! I meant that it is a bit obscure and this is why nobody edits it. Once the doc is with the actual source code then editing it will be more coupled with the development process itself. I think this is the biggest issue right now.
One option for images is to store them in git-lfs. That way they are versioned, but don’t impact cloning or take up space in the “real” repository (when they are not used). See this comment.
This is a great idea.
I think git-lfs is still a niche and can cause problems at many places, but if it is only used for documentation files then probably the impact can be minimized. If somebody does not bother with setting up git-lfs then only documentation files would be missed.
We would need to do some experiments if it works with web uploads and if automatic rules can be created that prevent accidental uploads of large documentation files as non-lfs objects.
I use git-lfs for large datasets in the VTKExamples. No probkems
It does require a client side intsall to see the files.