We currently manage the docs via a separate repo and should consider merging it into this main one, for these reasons:

1. Documentation is as an integral part of the project and a feature should not be finished until documentation is written for it. The current repo structure doesn't reflect this well (we often write documentation way after the main feature is finished & merged).
2. There would be a single contribution / review process.
3. Long-running branches (3.x, 4.x etc.) would be used naturally for documentation as well.

Points against it:

• We'd need to work out how to integrate this with our docs versioning ("version toggles" instead of branches).
• It might feel easier to contribute to a small, focused repo.
  • Not sure if this is a real downside, those who'd contribute would probably be fine with both options.
• Images: in a separate repo, it's not a big deal to have a folder like images. In this main repo, we want to watch out for any large binary files.
  • Images are aways a PITA. We should ideally cloud-host them.

Examples of project that have documentation inside the main repo:

• Calypso
• Git
• React, Angular etc.

Examples of project that have documentation as a separate repo:

• Symfony / Laravel / Nette
• Various Microsoft projects like VS Code, TypeScript etc.

🏁 Resolved by #1218