Dashboard: Migrate docs to wiki pages

[maciaszczykm]

[cheld]

Why? You cannot checkout wikipages or create PRs on documentation changes

[maciaszczykm]

Wiki pages are stored within a repository, so anybody can check them out:

However, it may be not possible to make pull requests for them.

I would like to move them because I think they are easier to discover for users. Today, with Sebastian, we have quickly initialized it so you can already check why I think that way. Sidebar menu with all topics is a lot easier to find than going through repository contents:

A lot of projects uses them. Kubernetes core does not need it (but still, wikis are available) because it has its own page with docs that are easy to find (kubernetes.io). Just check these wikis:

• https://github.com/google/closure-compiler/wiki
• https://github.com/angular/angular.js/wiki
• https://github.com/golang/go/wiki

All of these projects have their own generated docs (like kubernetes.io). I think our current docs folder looks like "sources" at the moment and is not user-friendly.

[cheld]

Ok, can external persons still make doc contributions? How is the workflow?

[maciaszczykm]

@cheld Currently it is disabled for our repository because if it would be enabled it would allow any logged in user to edit it. So either we can enable editing for everybody or we decide to maintain it by ourselves (it is not bad because we are doing it anyway). Contributors could still use issues to point issues in the docs (additionally we can ask them to do so in the footer visible on all wiki pages).

Another option is keeping important files here as origins and use wikis as a user-friendly mirror.

cc @floreks

[maciaszczykm]

A bit of info about wikis: https://help.github.com/articles/about-github-wikis/

[floreks]

I also think that wiki pages would be much more convenient for our documentation. We could keep README short and redirect users to our wiki where more detailed description of features could be provided. Currently it is not that easy (even for me) to navigate through our docs and find exactly what I need. Sidebar on wiki pages is really great and user can quickly discover what topics are covered.

As for external contributors I think it's good that only collaborators can edit it currently. Collaborators have best knowledge about the project and in case something is obscure then it can be pointed out in issues as @maciaszczykm mentioned.

[cheld]

Hmm..maybe free editing would motivate more contributions. We have all revisions and can compare and revert changes. I guess the idea is like Wikipedia - the more people are involved the better the quality will be

[maciaszczykm]

Yes, it is a good idea to encourage people.

[floreks]

I guess the idea is like Wikipedia - the more people are involved the better the quality will be

Yes but on wikipedia text can be first reviewed before it gets published. Here anyone could write whatever he wants and there is no clear way of avoiding that. Also wiki changes do not have any notifications for us so unless someone explicitly sees the changes, they can stay there for quite some time without review.

IMO documentation should be only changed by collaborators. They have knowledge about the project that allows them to add something meaningful. Strict documentation is not something that should motivate contributions. New contributors should first get familiar with the project, help us with bugs, features, etc. and once they gain collaborator status they can help with documentation.

[maciaszczykm]

It is done.