2.x: Update Wiki to the version 2 vocabulary and feature set

[akarnokd]

The current Wiki is mostly very old and is written in 0.x - 1.x vocabulary. Since those are end-of-life, they should be replaced by 2.x documentation.

Should we keep the v1 pages?

In a form of non Table-Of-Contents pageset?

How to enable community contribution to the Wiki content?

Editing the wiki is currently restricted, but the larger problem is, how to allow reviews on changes and how to allow the community to contribute small or large?

The wiki itself is under RxJavaWiki.git, but I don't think one can create a PR against it.

My idea is, create a wiki folder in the repo with the .md files and periodically synchronize it with the actual wiki.

Dedicated pages for operator groups?

There are at least 200 operators that could have a dedicated page with example(s), links to JavaDoc & other sources. These could be cross-base types in situations where the same operator is available in the 5-6 base reactive classes. The drawback is that there will be a lot of these. Would we want to spend time on this?

[akarnokd]

PR the wiki possibility: http://www.growingwiththeweb.com/2016/07/enabling-pull-requests-on-github-wikis.html

TLDR; create a separate repo for the wiki files, use scripts to sync back with the main wiki. Now that we have javadoc pushback, this could work.

[vanniktech]

Personally, I would not keep v1 pages.

My idea is, create a wiki folder in the repo with the .md files and periodically synchronize it with the actual wiki.

That sounds good.

There are at least 200 operators that could have a dedicated page with example(s), links to JavaDoc & other sources. These could be cross-base types in situations where the same operator is available in the 5-6 base reactive classes. The drawback is that there will be a lot of these. Would we want to spend time on this?

Focus on the main ones and maybe mention the other ones. Maybe we can also take most of the bits out of the Javadoc as it's pretty good.

[artem-zinnatullin]

My idea is, create a wiki folder in the repo with the .md files and periodically synchronize it with the actual wiki.

I think we should just store wiki as .md in the repo without syncing it to GitHub wiki and eventually disable GitHub wiki.

Search engines seems to be totally fine indexing markdown files in GitHub repos (I remember having some problems with it in past).

Frankly, I've never understood wiki on GitHub. It's hard to version it with the project, hard to contribute to it, as a result it's always somewhat out of sync and not part of main workflows.

Examples:

• storio/docs, we link to particular pages from README, you can also place README.md on any sub-folder level so it works like index.html
• Juno's Engineering Blog is basically markdown files without static website/wiki

Syncing it with GitHub wiki will be very similar to the problem of keeping changelog in sync both in file in the repo and in release section on GitHub, in this particular case I think it makes more sense to just keep wiki in the repo.

[akarnokd]

Posted #6047 . The wiki should be kept online as many may link to it already. After each release, I'll sync up the changes to the docs/ with the wiki

[artem-zinnatullin]

What about waiting for search engines to properly index wiki as files in repo and then updating GitHub wiki with something along the lines of "Wiki has moved into the repo [wiki/], this page can be found [here]."? Syncing it will be exhaustive unless automated and potentially confusing if users will start getting both options in search results.

…

On Sun, Jun 17, 2018, 2:24 AM David Karnok ***@***.***> wrote: Posted #6047 <#6047> . The wiki should be kept online as many may link to it already. After each release, I'll sync up the changes to the docs/ with the wiki — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#6001 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA7B3FKSVM6GB3W7mMdNugzJ561ymCIUks5t9iBTgaJpZM4T2PS9> .

[akarnokd]

I don't think we can do automatic redirect from within the markdown file. I can only disable wiki, not redirect it.

[artem-zinnatullin]

I meant just manual links to corresponding .md files (and maybe headers in them) :)

[akarnokd]

Work tracked in #6132.