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.
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.
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.
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 has gone unremunerated). I already frequently update the wiki.
Also note that here is a potential solution.
Colony is interesting, I think in the context that you need those with more knowledge and expertise in charge of approving edits or else misleading or incorrect information ends up on there (or it gets old)
Hey @ligi @jpitts should we move to this? Seems even more accessible than Github wiki, plus we can still use the Scrolls repo as the “source”? (that is, the pages are stored in the git repo, but you can edit / do things through the front end with no Github required).
@virgil do you have thoughts on what the scope of that wiki is? Great to see this! Is there a list of tasks for migrating somewhere that the community can help with?
Hi @boris, thanks for your comment. Please see my comment in https://github.com/ethereum/wiki/issues/589#issuecomment-410906496.
Issues so far:
- [ ] No soft wrap in revision history. E.g. in https://en.ethereum.wiki/hist/home, one paragraph appears as one line; and there is no soft wrap option, let alone by default. This doesn’t occur if you edit a page, just in comparing revisions.
- [ ] while history for a page is accesible by modifying the link, e.g. https://en.ethereum.wiki/faqs -> https://en.ethereum.wiki/hist/faqs, this is not a good UX; there should be a button to access history.
- [ ] no sidebar
- [ ] not able to search for content in pages
- [ ] pages appear to be out of sync, e.g. https://en.ethereum.wiki/edit/famous-bugs and https://github.com/ethereum/wiki/wiki/Bugs. https://github.com/ethereum/wiki/wiki/Decentralized-apps-(dapps) is missing (on the WikiJS site). https://en.ethereum.wiki/fundamentals/getting-ether exists, but it was confusing to navigate to https://en.ethereum.wiki/fundamentals (click all pages in the sidebar, then click the arrow in fundamentals), which should probably not be a page. If you don’t click the arrow but just click anywhere else on that Fundamentals line, it will take you to a list of sub pages in the sidebar.
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.
Process for Ring Formation
The goal is to make this preferred wiki. There will of course be others (e.g., ethdocs), that is more static documentation than a Wiki.
I would like these to be eventually be using the github.com/ethereum/ repo, but it’s not absolutely required. I suppose whenever people are willing to move, and they can simply clone from https://github.com/ethresearch/en-ethereum-wiki and I’ll point ethereum.wiki to sync against the new location.
@Jamesray1 wanted the existing sidebar imported into en.ethereum.wiki, so I did the best I could with that via tables. I’m sure we could do something more clever with raw HTML (and if we really wanted that I’ll do my best to figure it out). One nice thing about WikiJS markdown is that you can always insert raw HTML. So if anyone wants to have a go at it, .
@virgil it would be great if the server code could be checked into a repo and used as the meta-repo for working on improving the space. I’ve done a little bit of hacking on WikiJS and am figuring it out as well.
I understand nuking the issue queue, but if you want the community to help I think it’s most effective way to handle it. I don’t think which repo is used matters. The history from what I can gather is that no PRs were ever accepted and there was no process for people stepping up to become maintainers.
Are you actively looking for more maintainers? Is there a list / issue queue somewhere of what help is needed?