See discussion in #57, I try to summarize it here (feel free to discuss, challenge, improve...)

The pages in the wiki:

Intend to be community driven as anyone can update it easily without a PR. (we did see contributions from the community to add more pages like FAQ over time)

The items in the docs/ folder in the repo:

Is something that should be updated with approval/review as is represents the project viewpoints.

To avoid confusion, we might add a note on top of wiki pages, to indicate that there is more in the official docs. We also want to consolidate content by moving great wiki page contribution related to our project into our docs/ folder. I is more useful and easily discoverable by our users.

One example, there are at the moment 2 FAQ pages:

• The FAQ (wiki) is the community driven FAQ as anyone can update it easily without a PR. (we did see contributions from the community to add more FAQs over time)
• The Q&A in docs (mainly for the launch of openapi-generator) can not be updated without a PR.

Reason for using the main repo:

Multiple reasons for that:

• Documentation belongs to software change, have a look at this PR, it is great to be able to discuss what needs to be documented.
• GitHub Wiki does not support PR workflow, which is a great way to do suggestions, reviews and improvements
• Wiki are not forked in GitHub forks, you need to migrate them separately (they are git repositories, but not well integrated in GitHub UI).
• Pages inside a repo can be edited like a wiki, it supports all of github's templating (asciidoc, csv rendering, etc) and provide a better editor. Commits can be directly pushed (for owners) or a PR can be opened in a very easy way.
• Software documentation follows the software branches. Imagine we works on 4.0 and do some bugfix release for 3.0 on a separated 3.x-maintenance branch. With a GitHub wiki you just have a master branch, you can not support both versions in parallel.
• On the long term the plan is to generate the documentation inside a static website. For that we might need some artifacts that comes from the code itself (like for example the help in the command line that you have updated by hand). In the docs page there should be a placeholder that some content will be injected, and the static-website build tool should put the correct values in the built html manual. When we have this it make even more sense to single source everything in one repo and not in two (the main repo and the wiki repo)