Conan-center-index: [service] Make the documentation more collaborative

[danimtb]

Right now we are using the github wiki to document the things around ConanCenter and this repository. However, the documentation is not collaborative and can only be updated by the teams in the organization. Additionally, the wiki lives in a separate repo with a different lifecycle and cannot be checked offline.

In order to make documentation more collaborative, we are considering moving it to a folder inside the conan-center-index repo and creating a proper TOC markdown readme with the different sections. That will allow us to make the new updates more noticeable for all the community as well as encourage contributions with enhancements, fixes and suggestions around it.

Examples for this change https://github.com/conan-io/conan-center-index/issues/1837 and https://github.com/conan-io/conan-center-index/pull/1990#issuecomment-647270202

[uilianries]

Great idea!

It's possible to separate the Wiki, and create PR's, but it's a workaround: https://www.growingwiththeweb.com/2016/07/enabling-pull-requests-on-github-wikis.html

[danimtb]

@uilianries yes, but I think it is better to keep everything in this repo

[danimtb]

Done in https://github.com/conan-io/conan-center-index/wiki/Deployment-Changelog#17-july-2020---1854-cest and some work already started in #2124. Let's try to migrate the contents to readme and docs folder and then we will remove the wiki after the knowledge database links in the ConanCenter hook is redirected.

[Croydon]

@uilianries yes, but I think it is better to keep everything in this repo

I don't think that it has to be either or

I like the idea from the post @uilianries posted. In theory, we can use docs/* as the source of truth and just push everything from in it to the GitHub wiki.

This would be at least a nicer web view then the GitHub file preview. Or is something else planned for viewing the wiki/docs content online in a nice way?

[uilianries]

@Croydon unfortunately that workaround requires a new repo, and the CI will commit to wiki. I hope github can offer a smooth feature for wiki contribution in the future, but for now, we gonna move to docs/

As many times you read in CCI issues, seems like few people read the Wiki and they ask questions which are already listed and answered there. I think as Github Wiki is not so popular, people don't read regularly. So the idea here is pointing the docs in the README, which is more centralized and easier to be found.

A nicer viewer, like readthedocs it would be great, but requires extra maintenance. I don't know if it will be used.

[Croydon]

unfortunately that workaround requires a new repo,

It would not

1) Clone wiki repo
2) Delete all files in the current checkout from the wiki repo
3) Copy everything from CCI repo docs/* into the wiki repo
4) git add + git commit everything to wiki repo

and the CI will commit to wiki

At least the CI will push. If this is important we can copy over the name + email from the original commit. But I don't see a problem in that either way

I think as Github Wiki is not so popular, people don't read regularly.

I'm not sure if I'm that optimistic that people will read more when we change locations 😅

But we probably should update the current readme file. The entire section about the issues are obsolete since we added issues templates

[danimtb]

I think we all agree that moving the docs to the repo will be more collaborative and will help to improve it. We can think about pushing this to the wiki afterward, but let's take one step at a time

[jgsogo]

I think this task is complete. Having the docs in the repo makes them more collaborative, the next step will be to sync the wiki and the docs folder (I really think this is a nice and easy approach)...