Proposal: migrate select content to ethereum.org

[samajammin]

Hey folks!

Since the recent launch of our ethereum.org developer docs, we've received requests to migrate some content from eth.wiki to ethereum.org (particularly the JSON RPC spec).

Before we make any moves, I'd like to gather input (particularly from @ChrisChinchilla @wtf @jpitts) because I know you've all worked hard to get eth.wiki up & running. It's been (& will continue to be!) a tremendous resource for the community.

Why we think this is a good idea:

The community has pointed out multiple issues with eth.wiki:

• Duplicate content (e.g. https://eth.wiki/json-rpc/API & https://eth.wiki/en/json-rpc/api) Fix navigation #40
• Many links are broken [BUG] "Section pages" return a 404 #43
• Slow page load speeds Wiki is very slow #49
• Lack of basic features, like anchor links Clicking on a ¶ doesn't update the address bar #52
• Difficult to contribute to Define contribution permissions and workflow #41

ethereum.org has several advantages:

• We've taken efforts to solve for all the issues mentioned above
• We now have multiple full-time team members with the capacity to maintain & improve it
• Ability to translate content (via our translation program)
• The site gets significant more direct traffic & has the SEO authority to rank highly for content
• While we could link out to eth.wiki pages, the UX would likely be better if the pages were hosted directly on ethereum.org (e.g. so visitors can quickly find content via site search)

One potential vision moving forward

• eth.wiki serves as a "true" wiki, where anyone can edit the content without permission/approval. This could allow for rapid iteration & expansion of content, which I think our community could benefit greatly from, given how fast the space moves.
• ethereum.org continues to host tightly curated content, potentially migrating pages from eth.wiki once content has matured. Content here would be less comprehensive but developers can have high confidence that the information is accurate.

What a migration would entail:

If people are on board with this, I think the ideal approach with each page would be to:

1. Add the new page to ethereum.org
2. Update the link on the original wiki page (since GitHub doesn't support 301 redirects)
3. Set up a 301 redirect from the eth.wiki page to the ethereum.org page

I welcome thoughts & ideas around this! Cheers.

[jpitts]

On principle this is a good idea, but rather than think of it as a migration we should think of it as using source content to generate a more usable (and findable) representation.

For the case of JSON-RPC, this is a specification which constrains us. Wherever the actual spec is migrated, there needs to be a maintainer/governance of that resource, versioning, etc. A lot depends on its integrity and process. With this in mind, the JSON-RPC spec residing on the wiki is itself a problem IMO!

The website now has developer documentation, this is an opportunity to make specs more accessible and readable! There is probably a better way to format the JSON-RPC spec in that context. Perhaps the spec should reside in its own repo, but published to the website.

This is how EIPs currently works and it may be a good model, enabling the website to curate and add/remove parts of the spec so it is more readable and accessible to ethereum.org developer doc users.

[jpitts]

I hadn't realized it but the JSON-RPC spec is an EIP!

https://eips.ethereum.org/EIPS/eip-1474

The maintainers are organized via "Ethereum Oasis" and also work on projects like the Baseline protocol. https://github.com/ethereum-oasis/eth1.x-JSON-RPC-API-standard

EIP-1474 is likely to become the source of truth in this case, so this simplifies the matter. I'm curious about what changes you think will make this more useful for the intended reader on ethereum.org, or is the approach used on the wiki ideal for this use?

[samajammin]

Thanks for adding your thoughts @jpitts!

On principle this is a good idea, but rather than think of it as a migration we should think of it as using source content to generate a more usable (and findable) representation.

I'm on board with that framing. From a technical or operational perspective, would that change any of the steps I outlined above (particularly since the EIP is seemingly the source vs. the wiki)?

For the case of JSON-RPC, this is a specification which constrains us. Wherever the actual spec is migrated, there needs to be a maintainer/governance of that resource, versioning, etc. A lot depends on its integrity and process. With this in mind, the JSON-RPC spec residing on the wiki is itself a problem IMO!

I agree with this. I think it's another reason to host the content on ethereum.org, where we have defined processes around deploying updates. I think the fact the ethereum.org has more eyeballs on it means better scrutiny on its accuracy at any given time.

Perhaps the spec should reside in its own repo, but published to the website.

I'm open to that, though it would create more overhead for us to maintain (e.g. setting up a CI job to fetch the latest content on each merge). Do you see distinct advantages to this approach? Or alternatively, do you see disadvantages to the spec reference residing within the ethereum.org repo?

I'm curious about what changes you think will make this more useful for the intended reader on ethereum.org

A few immediate ideas:

• For each method, adding tables to view support across clients & versions (i.e. like Can I use)
• Creating executable code snippet examples
• Indexing each method in our site search
• Adding relevant links from & to the rest of the content
• Translating the content (not that this can't be done anywhere but ethereum.org has the technical capabilities to support translations & the volunteer base to make this easier/faster to achieve vs. elsewhere)

[fzeoli]

@tkstanczak is coordinating the JSON-RPC API standardization effort under OASIS, so he'll likely have a valuable take on this

[tkstanczak]

@samajammin - the recent work on ethereum.org is amazing. I have visited the page recently after a longer break and I was impressed by the improvement.
@jpitts, @samajammin -> one of the outcomes of our current JSON RPC effort will be some guidance on where the JSON RPC spec should be stored - currently users reach out to: eth.wiki, EIP-1474, go-ethereum docs, Parity docs, Infura docs, Nethermind docs and so on.
@fzeoli thanks for pointing me at this conversation

[tkstanczak]

@samajammin how does the editing process look on ethereum.org now? I think that when Oasis process for standardization finishes it will be great for your team to help with the general format of the spec. Would you like to included in the JSON RPC spec calls or prefer to be informed after the process finishes (and then clean the links / duplicates together)?

[samajammin]

@tkstanczak Glad to hear! Thanks for the kind words.

I read up a bit on the Ethereum OASIS Open Project - seems like a worthy initiative! I do wonder what you see as the end goal re: JSON-RPC. Is the vision to host specs & docs, similar to the Baseline repo?

Perhaps (to @jpitts's point) it would be best to host the canonical specs within the Ethereum OASIS repo to keep issues/PRs/discussion focused on that spec (vs. the ethereum.org repo, which has lots of other content & development activity going on).

That leaves me wondering if/where ethereum.org can help provide value. A few questions & thoughts:

• What's the timeline look like on the OASIS initiative? Depending on the answer, it may make sense to move these docs to ethereum.org in the meantime. I think most of us can agree that would be an improvement over the current eth.wiki.
• Given the authority of ethereum.org in the eyes of search engines, I do wonder if it'd be valuable to host any content there vs. creating a new documentation site within the ethereum-oasis repo. Perhaps the simplest approach would be to add it as a subdomain of ethereum.org that we could signal to from the root site.
• Regarding the spec calls, I'd be happy to join to discuss the end game options (though I doubt I'd add value as a regular attendee). I'll defer to you if that makes sense as an agenda item or if I should wait until the process finishes, at which point I could help with the clean up.

I'm open to ideas here. Just looking to improve the situation vs. the status quo, even if it's providing a short term solution 😄

[samajammin]

@tkstanczak following up on this - realizing I never answered your question!

@samajammin how does the editing process look on ethereum.org now?

All edits go through Github - you can learn more here:

• https://ethereum.org/en/contributing/
• https://github.com/ethereum/ethereum-org-website#the-contribution-process

Please let me know if you have any questions that these pages don't answer.

When you have time, please take a look at my thoughts & questions above. Thanks in advance!

[samajammin]

@tkstanczak nudge 😄 - any update on this re: planned migration of the JSON-RPC API docs?

Thanks

[samajammin]

Separately, pinging @ChrisChinchilla & @wtf again - do you folks have any thoughts/concerns about porting content from eth.wiki to ethereum.org? Thanks!

[ChrisChinchilla]

@samajammin I thought this was something we had discussed before this migration process started tbh, but I am not really working for the EF anymore anyway, so feel free to go ahead with whatever path you want.

[samajammin]

Hey @tkstanczak checking in on this. The ethereum.org team would like to assist with this initiative where you think it makes sense! Please let us know.

[samajammin]

Ping @tkstanczak

[samajammin]

Hey @tkstanczak - checking in again. Any update on this re: planned migration of the JSON-RPC API docs?

For now we're planning to move this over to ethereum.org. Happy to collaborate on an alternative if it makes sense.

[samajammin]

Opened up an issue on ethereum-oasis-op/eth1.x-JSON-RPC-API-standard#8

[tkstanczak]

Hi @samajammin apologies, I simply have too many GitHub notifications and never read them. Need to get it fixed somehow.
Would you join us on Discord: https://discord.gg/Upvr757b

[samajammin]

Some discussions around redirecting eth.wiki to ethereum.org have resurfaced, notably around some efforts to rename repos & community content as we approach the merge. More context here: ttps://notes.ethereum.org/@timbeiko/great-renaming

Does anyone have any thoughts or concerns about moving forward with this?