git – Managing Documentation / Source Control for a Full-Stack Application Across Multiple Repos

TL;DR

I have a moderately sized/complexity web application (Angular 11) in one repo and a standalone REST API (.NET Core 3 / C#) in another repo, and am trying to figure out the most efficient way to include MkDocs / Read the Docs in the project.


We’ve been building a full-stack web application with multiple core components in two repos:

  1. Frontend
    • Angular 11 Web application (compiled / deployed as a standalone app and not served from .NET)
  2. Backend
    • .NET Core 3 / C# REST API
    • RabbitMQ brokers for handling certain asynchronous actions
    • Windows scheduled task / console app for a nightly job

This has worked reasonably well, but as we’re building out the documentation more and more we’re running into documentation consistency issues across the two repos. E.g. in describing certain elements of the front end it makes sense to discuss the data, as this is a very “data-centric” app. However then it seems redundant to discuss those concepts in the documentation for the backend repo.

I’ve read a lot about the “monorepo vs. multi-repo” debate, and this seems to be a matter of opinion with some folks for one and strongly opposed to the other, and vice versa. (Similar post here).

As I see it I have a few options:

  1. Maintain multiple repositories as I have it now, and deal with the documentation headaches

    • Default option right now, as it requires no additional effort at this point in time
  2. Merge everything into a monorepo, which makes documentation easier but

    • As the project grows and more developers / analysts join, this could potentially complicate things (or, so I would expect?)
  3. Create a separate repository solely for documentation

    • Introduces more complexity to the scheme of things and possibly adds another barrier to developers updating documentation

What are some recommendations based on what other teams are doing?