Moving docs to a separate repo + using another tool for its maintaining

[andrii-bodnar]

I would like to discuss the possibility to move the Docs into a separate repo alongside its redesign and migrating to some modern documentation framework.

Storing the documentation code along with the rest of the code (monolithic repository):

Pros:

• Easier to maintain and update documentation as it is in the same place as the code
• Easier for contributors to make changes to both code and documentation at the same time

Cons:

• Could make the repository larger and harder to navigate for those only interested in the code
• May make it harder to separate concerns and track changes to documentation separately from code changes

Storing the documentation code in a separate repository:

Pros:

• Keeps the code repository clean and focused on the code
• Makes it easier to separate concerns and track changes to documentation separately from code changes
• Separate CI/CD processes (build, validation, deployment, etc)

Cons:

• May make it more difficult to keep documentation and code in sync
• Could make it more difficult for contributors to make changes to both code and documentation at the same time

---

Also, there are a lot of popular and great tools for docs management, for example:

• docusaurus.io
• nextra.site
• vitepress.vuejs.org
• etc.

These tools are based on MD/MDX which is the leading way of managing documentation nowadays (this discussion has already had place before - #837).

In the case of using such tools, it makes even more sense to split the docs into a separate repository.

[fromthemills]

Think this is a very good change. I would love to help out. I could sponsor a version of the Tailwind UI Protocol template. It's a more bespoke package than a docusaurus or nextra. But it keeps things simple and uses Next, MDX and tailwind as its core.

[andrii-bodnar]

@fromthemills thanks a lot for your suggestion but we decided to use Docusaurus and actually almost finished this - #1365

[fromthemills]

No probs! Looks great!

[andrii-bodnar]

https://lingui.dev 🚀