Post History

Generally speaking, if two groups of people collaborate on the same software, I'd recommend they put everything in a shared git repository:

* Documentation is intimately tied to the **version** of the software it describes. Looking at code examples in version X while writing docs for version Y is generally a mistake and should ideally be prevented by tooling. If everything lives in the same repository, git will default to checking out the same version of everything, and if you ask git to check out a different version it will automatically do this for both the code and the documentation. Submodules won't do that.

* Putting everything into the same repo removes artificial barriers to collaboration. Each group can look at what the other group did, and propose changes to the work of the other group in a way that is trivial to integrate (unlike git subtree, which makes this somewhat hard, especially if changes flow in both directions). For instance, a developer making a change to an API could see how that API is documented, and in the same commit update both the code and the documentation, send this through a review by both groups. I realize the groups may not currently work together so closely, but this may be simply because their current tooling has made it hard to do that, and say nothing about the value of closer collaboration. I emphasize this because in agile software development, both developers and documentation specialists are usually considered to be part of the same, cross-functional team. Creating separate teams is not regarded as best practice because it impedes sharing and collaboration.

With that out of the way, let's look at the impediments you mentioned:

>  Developers thus have Linux environments. For reasons I can't change, the doc team uses Windows but can ssh to Linux machines to run the software

That's totally fine as far as git is concerned. Git allows you to check out, edit, and commit changes to a file created under a different operating system, and will even convert line endings for you if you so configure it.

If the concern is being able to run the software: if you're on Windows 10, you may be able to use the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/faq) to run your Linux app directly under Windows.

> The dev repository is large. We don't want doc to have to check it out, especially because they wouldn't actually be able to do anything with it on Windows.

Just how large are we talking here? And how come the size is a problem for the docs team, but not the dev team? After all, it's the same size for both ...?

Unless its hundreds of megabytes, I probably wouldn't mind - disk space is cheap, and git is really good with doing incremental downloads, so this only affects the initial check out, but not your everyday work with git.

If the repository is so large that cloning and working with it is a real pain, then I wonder how the developers cope? Do they have some tricks they might share with you? Or are they suffering too? If so, why don't they make their repository smaller?

> Dev and doc both use the same branching policies, though not the same timing. (As is usual, doc lags dev a bit at the end of a release cycle.)

For branches, the doc team could simply keep committing even after the dev team is done. For instance, if you have a branch named v1.6 you could keep committing to that branch even the devs have released v1.6.

For tags, you obviously can't do that - but does the doc team need those? 

**Summary**

In summary, sharing a repository can offer you a more seamless collaboration with the development team than `git subtree` or `git submodule`, is much easier to understand for your git newbies, and seems doable in your situation. It's therefore the option I'd investigate first.