search

ethereum / wiki

The Ethereum Wiki
https://www.ethereum.org
14.75k stars 2.57k forks source link

A proposal to move the content in ethereum/wiki to a Wikipedia-style wiki site #589

Open jamesray1 opened 6 years ago

jamesray1 commented 6 years ago

Github wikis have the limitation that anyone can edit them while it is difficult to moderate them (it is not possible to watch a page to get updates for changes), which is a double-edged sword, in that it is great for non-censorship which is in the spirit of the Ethereum philosophy, however it is also prone to graffiti, bias, etc. Because of this limitation of lack of ease for moderation, we should consider moving the content in this wiki to a wiki site, e.g. one that is hosted by Media Wiki, adding a deprecation notice to this wiki and refer to the proposed new Media Wiki hosted site. This would have the benefits of anyone still being able to edit the wiki (they do not even need to create an account, although there are advantages to doing so), as well as being able to more easily moderate content. In order to move the contents of this wiki to another site, we would need a site that is compatible with Github Flavoured Markdown, to prevent manually changing the syntax to support the new site (or using a conversion tool); and it would need to have moderation features like Media Wiki sites, such as the ability to watch a page and get email notifications of any changes. There is a list of other Ethereum wikis and documentation.

Also posted in https://ethereum-magicians.org/t/a-proposal-to-move-the-content-in-ethereum-wiki-to-a-wikipedia-style-wiki-site/265 and https://github.com/ethereum/EIPs/issues/1053.

jamesray1 commented 6 years ago

This is one example of an issue of not having adequate moderation ability: https://github.com/ethereum/wiki/issues/591.

jamesray1 commented 6 years ago

See https://www.quora.com/Whats-a-good-host-for-a-wiki-site-that-has-watch-ability-for-pages-with-email-notifications-for-changes-and-compatibility-with-GitHub-Flavoured-Markdown for a potential solution.

jamesray1 commented 6 years ago

Just clarifying that I don’t want to work on moving the wiki to a Mediawiki hosted site because I need to focus on sharding development and get a grant and funds (so far my work, including editing this wiki and other docs, has gone unremunerated). I already frequently update the wiki.

fubuloubu commented 6 years ago

We are looking at gitbook for SecurEth, it is definitely pretty interesting so far. I like that it can be backed by GitHub so you can have tighter control over how updates get made.

jamesray1 commented 6 years ago

I already looked into that plus other alternatives, but it doesn't allow anyone to edit like Mediawiki sites, yet also have better moderation features like watching pages.

Also, if moving content to a Mediawiki site, all the cross-links to elsewhere within the wiki would need to be updated.

virgil commented 6 years ago

I have a beta working at: http://ethereum.wiki.

They are backed by:

jamesray1 commented 6 years ago

Great! Would be good if there is a way to watch a page and get notifications for changes, plus other features for moderators. See https://www.quora.com/Whats-a-good-host-for-a-wiki-site-that-has-watch-ability-for-pages-with-email-notifications-for-changes-and-compatibility-with-GitHub-Flavoured-Markdown for a potential solution for that with a MediaWiki-hosted site. Otherwise without that I'm not sure how much value the wiki site adds.

virgil commented 6 years ago

Yeah I tried MediaWiki---I wasn't able to get it as pretty as I desired. Also the editing was kinda meh for markdown.

I think as-is I'm pretty committed to WikiJS. There is a new version coming out (WikiJS 2.0) where we'll be able to get feature requests like that.

Note that you can get history pages on WikiJS, for example: https://en.ethereum.wiki/hist/home

jamesray1 commented 6 years ago

Fair enough, I did remember WikiJS mentioning that update, let's wait until then.

jamesray1 commented 6 years ago

I do like the sidebar of this github wiki/wiki, while that's not on the current site. It makes it easier to navigate and categorise things. It's good that the search bar is displayed top centre on the site, and that it seems to work when searching for page titles, but not for content in pages.

jamesray1 commented 6 years ago

I guess that the disadvantages of having a sidebar is that there is less space for content, and it could become cluttered over time as more information is developed about the Ethereum ecosystem.

jamesray1 commented 6 years ago

Issues so far:

I would probably consider any one of the above issues to be a deal breaker to using the wikiJS site over the GIthub wiki, especially without wikiJS 2.0.

Also, there is no ability yet to watch a page and other features for moderators, but this can't be considered an issue as Github wikis do not provide this feature yet either, nor have they committed to doing so, while it is planned for WikiJS 2.0.

virgil commented 6 years ago

  1. You're right that the lack of soft-wrap sucks. I suppose we can do a pull request for it---that's an easy fix.

  2. The UX for history comparison does indeed suck. It's an undocumented and never finished feature. In the mean time, one can use Github. E.g., https://github.com/ethresearch/en-ethereum-wiki/commits/master/home.md

  3. Wait, there is a sidebar, it's just on the left. See: https://en.ethereum.wiki/home

  4. You can. Maybe it's just complete words? E.g., search for "japanese" in the top bar and you'll see the the "Home" link.

  5. The synced github repos are:

I tried a few other wikis, my second choice was DokuWiki. But WikiJS was the best I found and I agree completely that we will upgrade to WikiJS 2.0 once it exists.

jamesray1 commented 6 years ago

Wait, there is a sidebar, it's just on the left.

Right, I guess it needs better categorisation into folders like on https://github.com/ethereum/wiki/wiki, which I prefer as it targets beginners with basics at the top, followed by R&D (which is arguably more important for scalability and thus overall use of Ethereum, than client development, dapp development, infrastructure, etc.) The sidebar on the Github wik categorises key pages so that you don't have to go to "all pages" to find frequently used pages.

You can. Maybe it's just complete words? E.g., search for "japanese" in the top bar and you'll see the the "Home" link.

Hmmm, maybe the site has been crawled recently as when I searched for e.g. "Plasma" before, it didn't come up in the sharding FAQs, but now it does.

The synced github repos are:

I see, so changes to https://github.com/ethereum/wiki/wiki are not synced with https://en.ethereum.wiki and vice versa. That could be problematic in between the transition to deactivating the former and only using the latter.

I moved a couple of unaddressed issues into separate checkboxes:

I'm not sure how / if I can edit the all pages navigation to add pages to categories and create new categories myself.

virgil commented 6 years ago

I'm wholly down for moving these into the official Ethereum repo. I often use the ethresearch GitHub as a sandbox before things are ready for primetime. If you'd prefer to move this over to the Ethereum GitHub now I'm all for it.

On Wed, Aug 8 2018 at 08:04, < notifications@github.com > wrote:

Wait, there is a sidebar, it's just on the left.

Right, I guess it needs better categorisation into folders like on https://github.com/ethereum/wiki/wiki , which I prefer as it targets beginners with basics at the top, followed by R&D (which is arguably more important for scalability and thus overall use of Ethereum, than client development, dapp development, infrastructure, etc.) The sidebar on the Github wik categorises key pages so that you don't have to go to "all pages" to find frequently used pages.

You can. Maybe it's just complete words? E.g., search for "japanese" in the top bar and you'll see the the "Home" link.

Hmmm, maybe the site has been crawled recently as when I searched for e.g. "Plasma" before, it didn't come up in the sharding FAQs, but now it does.

The synced github repos are:

I see, so changes to https://github.com/ethereum/wiki/wiki are not synced with https://en.ethereum.wiki and vice versa. That could be problematic in between the transition to deactivating the former and only using the latter.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub ( https://github.com/ethereum/wiki/issues/589#issuecomment-411240756 ) , or mute the thread ( https://github.com/notifications/unsubscribe-auth/AAE9qhRix-s1Ce88UG_ZKPcu507249xKks5uOiskgaJpZM4TyADC ).

jamesray1 commented 6 years ago

It'll need to be done eventually, otherwise discrepancies between the beta site and the wiki/wiki will continue to widen. As long as syncing doesn't cause anything untoward then I don't see why not, and I guess it could be reverted if needed.

virgil commented 6 years ago

We probably don't want make github wiki an official frontend because Github Markdown is slightly different from regular markdown (which WikiJS uses). However, if the ethereum github clones the wiki repos on ethresearch I will set the backends to the repos on the ethereum github instead of ethresearch.

jamesray1 commented 6 years ago

I think the problem with that is if the Ethereum Github wiki clones the ethresearch repo, which is syncing with ethereum.wiki, some data will be lost, e.g. missing pages on ethereum.wiki like https://github.com/ethereum/wiki/wiki/Decentralized-apps-(dapps); and edits made that aren't showing on ethresearch, e.g. this has edits made 4 days ago: https://github.com/ethereum/wiki/wiki/Decentralized-apps-(dapps)/_history, but this was last edited 18 days ago: https://github.com/ethresearch/en-ethereum-wiki/blob/master/decentralized-apps-(dapps).md. I checked that the Decentralized-apps-(dapps) page is not missing on the ethresearch repo: https://github.com/ethresearch/en-ethereum-wiki/blob/master/decentralized-apps-(dapps).md.

virgil commented 6 years ago

I will volunteer to personally see to it that house edits are included in the new wiki.

On Wed, Aug 8 2018 at 15:18, < notifications@github.com > wrote:

I think the problem with that is if the Ethereum Github wiki clones the ethresearch repo, which is syncing with ethereum.wiki, some data will be lost, e.g. missing pages on ethereum.wiki like https://github.com/ethereum/wiki/wiki/Decentralized-apps-(dapps) ; and edits made that aren't showing on ethresearch, e.g. this has edits made 4 days ago: https://github.com/ethereum/wiki/wiki/Decentralized-apps-(dapps)/_history , but this was last edited 18 days ago: https://github.com/ethresearch/en-ethereum-wiki/blob/master/decentralized-apps-(dapps).md . I checked that the Decentralized-apps-(dapps) page is not missing on the ethresearch repo: https://github.com/ethresearch/en-ethereum-wiki/blob/master/decentralized-apps-(dapps).md .

— You are receiving this because you commented. Reply to this email directly, view it on GitHub ( https://github.com/ethereum/wiki/issues/589#issuecomment-411310789 ) , or mute the thread ( https://github.com/notifications/unsubscribe-auth/AAE9qhh6WeLAdHWCITNUFjEh8RS-OANRks5uOpDQgaJpZM4TyADC ).

jamesray1 commented 6 years ago

OK. I'd like to be able to categorise the "all pages" better before moving to the new wiki. E.g. like on the sidebar here https://github.com/ethereum/wiki/wiki with a categories for R&D; clients, tools, dapp browsers; APIs; languages; etc; infrastructure; dev technologies; Ethereum technologies, etc.

virgil commented 6 years ago

Sure. Will include any of the sidebars you'd like.

virgil commented 6 years ago

I've made the sidebar on https://en.ethereum.wiki/home via tables. It's not pretty, but it's not terrible. We can probably do better.

I have re-organized a few bits putting things into subfolders, etc. I'm not wedded to the categories I chose. If you want a different structure I have no complaints.

jamesray1 commented 6 years ago

Thanks, in one sense it's actually easier to navigate to those pages as you don't have to scroll down the page. A disadvantage is that it's only on the home page, not every page, but at least you can get to the home page easily.

Some of the pages in those tables didn't/don't exist. I created pages for a lot of missing ones in basics: Decentralized apps (dapps), an intro; getting Ether; Design rationale; glossary; as well as R&D: the compendium, https://en.ethereum.wiki/alternative-blockchains-randomness-economics-and-other-research-topics, https://en.ethereum.wiki/governance-compendium, https://en.ethereum.wiki/Ethereum-Virtual-Machine-(EVM)-Awesome-List, https://en.ethereum.wiki/Clients,-tools,-dapp-browsers,-wallets-and-other-projects, and https://en.ethereum.wiki/dapp-development. There may well be others. There may have been a more automated way to do that, but meh. I just copied and pasted the content of the corresponding pages in the Github wiki, so any links that direct to GitHub wiki pages will need to be changed.

The link for ICAP:-Inter-exchange-Client-Address-Protocol didn't work, presumably due to the colon. I created a page at https://en.ethereum.wiki/inter-exchange-client-address-protocol-icap and accordingly edited the link.

Deleted a blank exchange integration page on the GitHub wiki and removed links to it in the sidebar on both sites.

Another disadvantage to the wiki JS site related to editing and history is that when you edit you can't enter a short summary of the edit.

I went through the links in the first table.

Of course, syncing en.ethereum.wiki with this repo is probably a good idea now, rather than manually editing stuff like I've done above. Like I said, if there are really bad problems that are hard to fix (which seems unlikely), that can always be reverted.

ghost commented 6 years ago

newb diving into eth wiki, i would soo appreciate default wikipedia style, the tools are opensource; dont reinvent the wheel. @jamesray1 excellent suggestion

jamesray1 commented 6 years ago

Moving to a Wikipedia style would involve either making it compatible with GitHub Flavoured Markdown, or updating the wiki to conform to Wikipedia syntax. The former should be easier, as mentioned above, see https://www.quora.com/Whats-a-good-host-for-a-wiki-site-that-has-watch-ability-for-pages-with-email-notifications-for-changes-and-compatibility-with-GitHub-Flavoured-Markdown for a solution. It would be less effort to wait for wiki-JS 2.0.

nhandl3 commented 5 years ago

Sorry I don't have much experience with MediaWiki yet but I have a question. You @jamesray1 said that it's hard to moderate change with Github's Wiki. Why don't we use Github's repo itself to manage changes? We can fully version control with repo, making issue/PR for change request & review. There are some projects documenting this way (Github themselves) and pretty good in control.

For example atom project, this final page https://flight-manual.atom.io/getting-started/sections/why-atom/ and here is its repo history https://github.com/atom/flight-manual.atom.io/commits/master/content/getting-started/sections/why-atom.md

Long ago before moved to Github's wiki, you guys also used repo. Can I know the reason for it? IMHO, current tooling is good enough to publish document directly from Github's repo.

jamesray1 commented 5 years ago

Because people can make changes to the wiki directly. While spam edits and the like occasionally happen, IMO the wiki is still better as it saves needing a maintainer to review trivial edits. With no maintainer allocated to the task and dozens of PRs being left open and unattended, I decided to try to point people towards being more proactive by editing themselves, filing an issue with relevant parties e.g. for Mist, web3, etc. A wiki is more decentralized, being freely maintainable by the community, rather than being controlled by the Ethereum Foundation.

If you are interested in being a maintainer you could try talking to someone in the Ethereum Foundation such as @Souptacular.

jamesray1 commented 5 years ago

Someone has removed the sidebar and changed the footer to an ethereum address. :(

virgil commented 5 years ago

Here we go, https://eth.wiki .