EIP-1053: A proposal to move the content in ethereum/wiki to a Wikipedia-style wiki site

I agree that GitHub Wikis don’t really work that well.

The question becomes what to move to, and the bike shedding around what system to use, who will maintain it, etc.

The wiki functionality here in Discourse, for instance, works and has great discussion forums, but doesn’t do cross page linking syntax very easily.

Do you have some thoughts on the goals & scope of the Ethereum wiki? Who is the audience? What content belongs, vs which doesn’t?

1 Like

Right now those working on documentation aggregate in the ethereum/documentation Gitter channel: https://gitter.im/ethereum/documentation

I’ll post a link to EIP-1053 there…

1 Like

Hi Boris, like Wikipedia, the audience and content of the wiki could be very broad, covering the whole Ethereum ecosystem, but there is content that is more relevant to different groups, e.g. users, researchers, dapp developers, core developers, sharding researchers and developers, Casper researchers and developers, enterprises, etc. Lots of content could potentially be in one wiki site, provided that it is well organized and searchable.

I think the wiki is useful for people who are interesting in contributing in getting up to speed.

Everyone you’ve listed is mainly involved in technical efforts. BUT – even there, user researchers and designers need to optimize for different things than slightly-better-than-Github-wikis that might be a fit for documentation writers and devs. Internationalization and versioning might be most important for doc writing, for example.

We have to understand who the audience is and who is taking responsibility. Which “entity” will run a single Ethereum wiki? How do we both collaborate and intensify efforts around one repository, while leaving room for other groups to run parallel efforts (forking documentation?).

I am even sensitive to colonizing this site. Have had great discussions with @jpitts on Twitter, but am essentially “assuming” that I can move in and use the Working Groups space as an area to document best practices for having technical / design / etc. meetups.

Anyone: question 1 is – which entity (including no entity, just a group of people who do it) will take responsibility for hosting, running, and maintaining the wiki at a technical level, as well as at a moderation level.

Essentially, who gets to say “no”?

I’d love to see efforts like this go into a grant system as well. Let’s gather some funds so N people can work on it for three months. This is what I am exploring – the collaborative funding and support model, so it doesn’t all have to get done by one Foundation or a small group of privately held companies.

3 Likes

We do need a working group for operating “Online Presence”, one of the practices described in https://goo.gl/DrJRJV. This would include https://ethereum-magicians.org and any future web site.

Currently, I am looking after this Discourse website, but over time we will add moderators and it will become more formalized.

As for the Wiki itself, this is an entirely different beast. It needs more champions (there are some very good ones, but perhaps not enough). It needs governance.

3 Likes

Here’s an example of an Ethereum focused wiki that is very specialized http://tokenengineering.net/

That’s Trent McConaghy of BigChainDB / OceanProtocol who kicked it off.

Bottom line: great idea, pick a topic / area of interest / type of audience and gather a group to host it and maintain it and go from there.

3 Likes

Personally I’ve already spent a lot of time editing docs pro-bono, so I’m not keen to create a new wiki site and copy and paste the contents of the Github wiki to the new site. Additionally if the syntax of the wiki doesn’t support Markdown then it would have to converted (manually or automatically if there’s a tool for that). I had a look at http://doc.wikidot.com, but it doesn’t support [link](URL) style links.

If you just want people to have a nicer experience reading the wiki, you could easily port it over to mkdocs. I made the Giveth wiki, using mkdocs with material theme - it takes markdown files and renders them out nicely. Have a look at https://wiki.giveth.io

It is mainly a task of setting up mkdocs, write a mkdocs.yml file for site structure, choose a theme and host the thing (we use netlify). If you don’t want to do it, or don’t want to do it pro-bono, we can put it up as a task for Giveth social coding with a bounty attached.

2 Likes

Yes, this is exactly my point! You’re already at the point where you feel that your contribution isn’t being valued.

Someone has to choose to host and maintain such a thing. You don’t need permission if you want to do it. If you need resources, you’ll need to gather supporters and help.

I don’t know who runs these other wikis:

It might be interesting to start by curating a list of all the wikis, who runs them, what is their intended audience, and then go from there.

Let me know what you need help with.

3 Likes

Hmm, it’d be interesting to see if you can use the wiki in a repo, rather than the code, to generate the site.

I’m working on sharding development, there is a lot to do there (and Drops of Diamond has not received a grant for that yet either). So I need to limit my time that I spend on other things as much as possible. I’m happy to spend a bit of time updating the wiki, mainly on sharding, with new research as it comes out, but I don’t have time to set up a new site.

Interesting, I haven’t seen https://theethereum.wiki/w/index.php/Main_Page before! Still, this is a MediaWiki site, so it won’t be easy to move all the Github wiki content to this site, and the syntax isn’t as nice. The site isn’t active. there are junk pages and you can’t create an account and edit pages. But due to the syntax I don’t think we should revive it or use a MediaWiki site.

Ethdocs is a historical reference for Homestead, I submitted a pull request on the source code to that effect last week which has been merged. I submitted another PR just now to update the site, not just the repo.

I’ve started a list here.

More sites were suggested here.

In response to “working group” style wikis, I am a member of the SecurEth.org team who has a foundation grant to create Smart Contract Development Software Engineering guidelines. Part of that is coming up with a governance structure for how that effort accepts proposals and makes edits, in order to ensure the proposals capture the spirit of what guidelines are (“why” do something and multiple suggestions for how) and actually stay relevant to the reality of the ecosystem.

I think if we’re discussing multiple working groups (UX/Wallet, smart contracts, front end UI, token engineering, etc.) there should be a meta conversation here, and some sort of organization of those efforts so we don’t end up with multiple different sources of “truth”.

This is a growing pain I think. The realization that there are multiple “jobs” that need to get done, and ad-hoc wikis are not the best way to organize these efforts.

We have a guidelines repo I was intending on using in this way.

This is the right approach

Personally, I think that main Ethereum wiki should be focused on describing different parts of the protocol and it’s development (like sharding). It should be a great resource for client developers and core devs for helping organize and document the extensive efforts going on here. There has been fantastic work done here, and focusing it allows it to have even greater detail and utility to the audience you serve.

Again, as it grows, you might want to implement a governance structure to ensure at least a subset of client developers and core developers agree on the wording and language used as accurate and understandable. I see this being more of like an EIP editor role, rotating on a regular basis and only concerned with structure and voice and ensuring consensus, and not making any political decisions.

1 Like

Maybe all these subgroups can adopt this one style (style uniformity) but each pick a different color o’ the rainbow (differentiation).

Would also be neat if we could have like an “Ethereum theme” repo we could all pull from for our respective wikis

I think wikis serve best at introducing people to a topic. They shouldn’t be regarded as something that you can formally cite since the content can change at any time and isn’t subject to academic peer review. If you’re going to have separate wikis for different topics then I think there should be somewhere that lists all of them, to make it easier to find what you are looking for from one place. However if you have one wiki with content on different categories then you can search more specifically on that wiki to find what you’re looking for. And there may be overlap between categories which would come up in search results on one wiki, but not on different wikis.

Definitely agree it should not be a formal document release and that it needs to be approachable from both a reading perspective and an editing perspective, I do however disagree in that an editorial review process would help each article fit the overall narrative better and ensure that only high quality suggestions (i.e. those that help guide newcomers) make it in. We also plan a more formal set of guidelines that would be peer reviewed and released.

The individual wikis can be linked together as a metawiki, buy I think each large section needs it’s own group of editors and administration to be successful. This is especially true for the smart contract guidelines we are working on because they will ultimately enforce formal communications between developers and security auditors, and serve as the basis for a quality standard that people external to our community can understand when using products developed on the Ethereum platform. An unmanaged wiki-based process alone wouldn’t provide an adequate foundation for that.

1 Like

https://colony.io/ Could be potentially used to manage and track the tasks that need to be done for online presence. While some of us may not have time, others can come and pick up items to wrangle.

1 Like