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

Question

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?

Answer 1

Generating documentation is one of the tasks that build servers excel at. Part of the continuous integration pipeline could include generating the documentation for each project, and then publishing that documentation to a web server where it is centrally accessible to your team members.

Include instructions in each project on how to build the documentation locally for work in progress that has not yet been merged into your main line branches. Many build tools allow you to do more than just build a solution or deploy files. You could include generating the docs as part of building the solution, or create a PowerShell script that does this for developers and testers.

Really the point is to get rid of the repetitive stuff. Scripts and build servers are the go-to tools for this kind of work. Once you do this, whether or not you merge the two repos is irrelevant to where the documentation is kept and how it is generated.