In the last few weeks, I've been making changes to the documentation site that we had (https://docs.decidim.org - repository at https://github.com/decidim/documentation). Most notably, is that:

1. for the time being we're only working on an English version (before we had English / Spanish / Catalan, a maintenance/sync nightmare)
2. we're moving from multi repositories documents to a mono repository as it's easier/quicker/simpler
3. (related to 2.) we're deprecating lots of old docs repositories (moved to https://github.com/decidim-archive so we can preserve history but don't pollute https://github.com/decidim)

As you've seen, on the new doc site there are some sections that are copied directly from docs/ (at least the initial idea, as I've already made some changes):

• Installing: https://docs.decidim.org/en/installing/
• Customizing: https://docs.decidim.org/en/configuring/
• Developing: https://docs.decidim.org/en/developing/guide/

In the past we had something similar to a thing called the "developer manual" but it was a bad idea as it's difficult to maintain updated after we made the copy.

An important point regarding this issue is that both involve changing the format of the documentation, from Markdown to AsciiDoc. Basically, the issue with Markdown is that is not a standard, there are lots of flavors or versions: "MultiMarkdown, GitHub Flavored Markdown (GFM), Pandoc, CommonMark, and Markdown Extra among others." according to Wikipedia (WTF) - I hope that we don't have any fan of Markdown, AsciiDoc is pretty similar with a few minor differences and actually

1. Documents on decidim/decidim

One thing that the software that we're using (Antora) would enable us is to configure multiple documents on this same repository, the file structure would change a lot, something along the lines:

• docs/installing/
• docs/customizing/
• docs/developing/

Inside of every of this directory, the files should be something like (I'm not 100% sure, I'm not an Antora wizard yet 🧙):

• docs/installing/antora.yml
• docs/installing/pages/
• docs/installing/assets/

Pros

• Easier to reach to current developers
• If the code changes, the documentation changes (ie without issues that "we didn't updated the documentation because is on another repository).

Cons

• We'd need to do automation to rebuild when there's a change on docs/

2. Documents on decidim/documentation

Another solution would be to remove all the files on docs/ and put only a document explaining that we've moved to docs.decidim.org; maybe we should only leave the getting-started.md doc as it's linked from /system on a fresh install (although we should change that link to a page on docs site in the near future)

Pros

• Everything is in the same repository

Cons

• Is not that comfortable to the developers as reaching to docs inside this repository
• Synchronization issues (people might forget to update the docs in another repository?)

So, what's your opinion regarding this issue?
Do you prefer option 1 or option 2? Why?
Do you have another option to discuss that'd be better?