I just found this topic after recently working a lot on the docs. So let me add my thoughts.
I was pretty convinced that integrating the docs repo to the main one would be a good idea. The longer I think about it, the less I’m convinced for myself. Issues may be discarded I suppose, but Git history is definitely worth keeping, so there’s challenge number one. The harder part I see is actually CI / CD setup. The docs repo has its own build and deploy pipeline, which I find appealing and pretty streamlined. Mixing that with all the checks and actions happening on the code repo means quite a lot of runtime wasted and a fair bit of complexity to keep all parts moving.
Coming from my recent endeavours on completing API docs and configuration file options, I must say I’m a bit disappointed by the lack of docs adjustments for new features from the last couple of years – even though the PR template clearly demands a link to the corresponding docs PR. Not trying to blame here, but I think this needs more attention during the review process. I for one will strictly remind people of linking a docs PR before merging anything where I see the need to mention it in the docs.
Now the attempt to find an answer to the topic’s question. Like @imsodin, I’m actually undecided. My best answer would be: Partly. With lock-step tagging of both repos and some automation we recently added, the current situation is not really terrible. I propose to make a distinction between reference documentation (essentially all our .proto
s and the CLI) and every other kind (FAQ, handbooks / guides, how-tos, conceptual description / whitepapers). IMHO, an API reference is utterly useless if it doesn’t describe every interface (option, endpoint, whatever). So at least mentioning new interfaces even with a crappy one-liner description should be forced for every code contribution, in the same PR. Of course, generating such rudimentary API docs automatically is the best approach and easiest when integrated with the code repo.
Cross-referencing is a big issue if we were to split the docs in such a way. I must say I have come to like Sphinx and reST for those features, otherwise I wouldn’t have started implementing a Sphinx extension for documenting Syncthing’s config file. It’s immensely useful to add cross-references from prose text to the option / API references. But we could maybe still do that by pulling the reference docs from the main repo during the docs build procedure. I have no detailed solution in mind, so just putting the thought out there for further pondering.
Regarding editing format / experience, certainly the “guides” part could use some more human-friendly approach, maybe even a curated Wiki (while taking snapshots at release tagging time). But as long as we have a procedure for importing the updated reference docs to the user docs repo / whatever (kind of like the cycle for Transifex), allowing cross-reference links there should be doable.
Finally, whatever we end up changing here, I still seriously doubt that even a Wiki will lead to more independent contributions. So overall, every contributor just needs to apply a good measure of self-discipline to make rudimentary docs adjustments when adding features. And from time to time, make the jump and do some writing to extend those stubs into usable user docs. I’m trying to lead by example on that appeal