Skip to content
This repository has been archived by the owner on May 26, 2022. It is now read-only.
This repository has been archived by the owner on May 26, 2022. It is now read-only.

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

Open
jamesray1 opened this issue May 4, 2018 · 29 comments
Open

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

jamesray1 opened this issue May 4, 2018 · 29 comments
Labels
meta Sets standards on managing this repo and wiki

Comments

@jamesray1
Copy link
Contributor

jamesray1 commented May 4, 2018 •
edited
Loading

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 ethereum/EIPs#1053.
@jamesray1 jamesray1 changed the title A proposal to move the content in ethereum/wiki to a Wikipedia-style wiki site A proposal to move the content in ethereum/wiki to a Wikipedia-style wiki site May 4, 2018
@jamesray1
Copy link
Contributor Author

jamesray1 commented May 5, 2018 •
edited
Loading

This is one example of an issue of not having adequate moderation ability: #591.

@jamesray1 jamesray1 reopened this May 29, 2018
@jamesray1 jamesray1 added the meta Sets standards on managing this repo and wiki label May 29, 2018
@jamesray1
Copy link
Contributor Author

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
Copy link
Contributor Author

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
Copy link

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
Copy link
Contributor Author

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
Copy link
Member

virgil commented Jul 21, 2018 •
edited
Loading

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

They are backed by:

@jamesray1
Copy link
Contributor Author

jamesray1 commented Jul 23, 2018 •
edited
Loading

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
Copy link
Member

virgil commented Jul 23, 2018

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
Copy link
Contributor Author

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

@jamesray1
Copy link
Contributor Author

jamesray1 commented Jul 24, 2018 •
edited
Loading

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
Copy link
Contributor Author

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
Copy link
Contributor Author

jamesray1 commented Aug 7, 2018 •
edited
Loading

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
Copy link
Member

virgil commented Aug 7, 2018 •
edited
Loading

  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
Copy link
Contributor Author

jamesray1 commented Aug 8, 2018 •
edited
Loading

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
Copy link
Member

virgil commented Aug 8, 2018 via email

@jamesray1
Copy link
Contributor Author

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
Copy link
Member

virgil commented Aug 8, 2018

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
Copy link
Contributor Author

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
Copy link
Member

virgil commented Aug 8, 2018 via email

@jamesray1
Copy link
Contributor Author

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
Copy link
Member

virgil commented Aug 9, 2018

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

@virgil
Copy link
Member

virgil commented Aug 15, 2018

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
Copy link
Contributor Author

jamesray1 commented Aug 15, 2018 •
edited
Loading

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
Copy link

ghost commented Oct 4, 2018

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

@jamesray1
Copy link
Contributor Author

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
Copy link

nhandl3 commented Nov 8, 2018 •
edited
Loading

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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

@jamesray1 jamesray1 mentioned this issue Feb 26, 2019
Open
3 tasks
@virgil
Copy link
Member

virgil commented Jun 16, 2019

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

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
meta Sets standards on managing this repo and wiki
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@virgil @nhandl3 @fubuloubu @jamesray1 and others