Lighthouse: [Vote][RFC] Changes to the docs structure

[spawnia]

This issue aims to decide on how we go forward with the docs for Lighthouse. We aim to find the best solution for the following points.

1. How can we keep the docs in sync with the latest changes?
2. How easy is it to contribute to the docs?
3. How can we handle versioning?

@chrissm79 has done a great job with setting up the current docs page with docusaurus over at https://github.com/nuwave/lighthouse-docs. As the pace of development picked up, coordinating changes across the repos has become quite challenging.

@robsontenorio has come forward with the suggestion to put the docs right into this repo https://github.com/nuwave/lighthouse/pull/429. Many open source projects have had great success with this kind of mono-repo approach. Instead of going with Docusaurus, he has used Vuepress to rebuild the docs page.

[spawnia]

Vote here on how we should structure the repo in the future:

• 👍 Mono-Repo with a /docs folder
• 👎 Seperate repositories

[spawnia]

Vote here on the technology to use for the docs:

• 👍 Vuepress
• 👎 Docusaurus

[spawnia]

I advocate for having the docs in this repo, because it makes it easier to couple implementation changes with changes for the docs. A single PR should contain both, ensuring the docs do not get out of sync.

There is no downside for package users, since the docs will be excluded from the Packagist bundle. And we are not even close to having to worry about repo size.

[spawnia]

Technology-wise, i think Vuepress looks really promising. @robsontenorio has done a great job with making versioning work so we are not lacking features in comparison to Docusaurus.

There are a number of improvements:

• GraphQL syntax highlighting works
• Links between markdown files work in GitHub too
• Search works
• The site is way quicker/snappier to use

[robsontenorio]

You can learn about VuePress in https://vuepress.vuejs.org/

Just removed searchbox for a while, because by default it will return duplicated results between docs folder (2.6, 2.7 ...). Just submited a PR to VuePress core.

Please, comment in favor

https://github.com/vuejs/vuepress/pull/1032

[enzonotario]

Great @spawnia ! but I think that you mean @robsontenorio , I didn't do that great job! :)

[spawnia]

@robsontenorio @enzonotario Hahahaha sorry guys! You are both great :)

[olivernybroe]

Nice to see that we might be changing to mono repo! :)
Looking forward for this.

[chrissm79]

Thanks to everyone who voted! Resolved by #429