I've noticed that documentation for many applications tends to be found on a separate subdomain, like docs.domain.com, rather than directly on the main site like domain.com/docs. This pattern seems prevalent especially in monorepo examples where documents appear as a separate app. Can anyone explain the reasons behind this common practice?
6 Answers
Sounds like the general consensus is that subdomains for docs are a practical solution, especially for larger applications. It lets teams work more independently and maintain cleaner deployments! Thanks for all the insights, everyone!
Overall, using subdomains for documentation helps with versioning as well. It allows you to maintain different versions of your docs without too much chaos. Users can access docs for specific versions more easily with a subdomain like docs.domain.com/v1 instead of your main app domain.
One reason developers prefer subdomains is that documentation often uses different frameworks compared to the main application. For example, frameworks like Docusaurus make documentation easier to manage separately. Integrating it into the main site can complicate things, especially if the main app relies on a different tech stack.
Absolutely! It simplifies management and keeps everything organized.
Separate documentation apps can reduce the complexity of deployment. When the documentation has its own deployment pipeline, it won't interfere with the main app updates. This way, the documentation can use static file hosting which can be much simpler and cheaper than dynamic app hosting.
I've found that using a subdomain for docs is much easier than trying to integrate it into the main app's routing. It makes managing updates less of a hassle, especially when there’s a different team focusing solely on the documentation. Different release cycles and tech stacks can complicate things if everything is in one place.
Right! Keeping things modular helps prevent breaking changes across the board.
Also, isolating documentation from the main application improves security. If your app goes down, it’s beneficial for the docs to remain accessible. Plus, subdomains help with performance since static files can be served efficiently without impacting the main application’s resources.
That makes sense! Using existing documentation platforms saves time compared to building something from scratch.