Migrate materials from ethdocs.org

[jmcook1186]

Background

The homestead guide at ethdocs.org is now a historical archive. While it is full of interesting information it is now very out of date and users can easily be confused by contradictory information provided there compared to newer resources such as ethereum.org. Therefore, this issue is to suggest selective migration of material from ethdocs.org to ethereum.org such that the latter is becomes the go-to resource.

This has been discussed previously, e.g. on the ethdocs github here, but no action has yet been taken. Here, I have done a page-by-page audit of ethdocs.org and identified pages that can simply be deprecated using 301 redirects to the equivalent information on etheruem.org and which pages contain relevant material not currently included on ethereum.org that should be migrated across.

Note that there is crossover with another issue #5690 that suggests similar actions for the ethwiki. There, I suggested several new pages for ethereum.org that can also include material from ethdocs.org.

Below is a page-by-page audit for ethdocs with recommendations. Below are specific PRs that would address the suggested actions.

|   Suggestions     |                  Notes                         |  File
|-------------------|------------------------------------------------|-----------------------------------------------|
|                   |                                                ├── source                                      |
| Sunset            | Info specific to homestead guide               │   ├── about.rst                               |
|                   |                                                |   |                                           |
| Sunset            | OOD and geth specific. Redirect to geth docs   │   ├── account-management.rst                  |
|                   | and/or eth.org                                 |   |                                           |
|                   | /developers/docs/accounts/                     |   |                                           |
|                   |                                                |   |                                           |
| Sunset            | OOD - redirect to eth.org/developers/          │   ├── connecting-to-clients                   |
|                   | nodes-and-clients                              |   |   |                                       |
|                   |                                                |   |   |                                       |
|                   | docs/programming-languages/ruby                │   │   ├── ethereum-ruby                       |
|                   |                                                │   │   │   └── index.rst                       |
|                   |                                                │   │   ├── index.rst                           |
| Sunset            | /docs/programming-languages/dot-net/           │   │   ├── nethereum                           |
|                   |                                                │   │   │   └── index.rst                       |
| Sunset            | /docs/programming-languages/java/              │   │   ├── web3j                               |
|                   |                                                │   │   │   └── index.rst                       |
| Sunset            | /docs/apis/javascript/                         │   │   ├── web3.js                             |
|                   |                                                │   │   │   └── index.rst                       |
| Sunset            | /docs/programming-languages/python/            │   │   └── web3.py                             |
|                   |                                                │   │       └── index.rst                       |
| Sunset            | OOD redirect to eth.org:                       │   ├── contracts-and-transactions              |
|                   |/contracts-and-transactions/developer-tools.html|   |   |                                       |
|                   |                                                |   |   |                                       |
|                   | /developers/docs/smart-contracts/              │   │   ├── accessing-contracts-and-tra...rst   |
|                   |                                                |   |   |                                       |
|                   |                                                |   |   |                                       |
| Sunset            | OOD redirect to                                │   │   ├── account-types-gas-and-tra....rst    |
|                   | /developers/docs/accounts/#types-of-account    |   |   |                                       |
|                   | /developers/docs/gas/#top                      |   |   |                                       |
|                   |                                                |   |   |                                       |
| Sunset            | OOD redirect to                                │   │   ├── contracts.rst                       |
|                   | /developers/docs/smart-contracts/              |   |   |                                       |
|                   |                                                |   |   |                                       |
| Sunset            | OOD redirect to                                │   │   ├── developer-tools.rst                 |
|                   | developers/docs/ethereum-stack/                |   |   |                                       |
|                   |                                                |   |   |                                       |
| Sunset            | OOD, superceded by tests in execution/consensus│   │   ├── ethereum-tests                      |
|                   | spec repos which can be redirected to:         |   |   |     └── index.rst                     |
|                   | github:                                        |   |   |                                       |
|                   | /ethereum/execution-specs/tree/master/tests    |   |   |                                       |
|                   | /ethereum/consensus-specs/tree/dev/tests       |   |   |                                       |
|                   |                                                │   │   │                                       |
|                   |                                                │   │   |                                       |
| Sunset            | OOD superceded by Remix                        │   │   ├── mix                                 |
|                   | redirect to https://remix.ethereum.org/ or     |   |   |   |                                   |
|                   | eth.org/developers/docs/ides/#web-based-ides   │   │   │   ├── codeeditor.rst                  |
|                   |                                                │   │   │   ├── dapp-deployment.rst             |
| Sunset            | these tutorials are specific to the deprecated │   │   │   ├── dapp-deployment.rst~            |
|                   | web IDE Mix. Equivalent tutorials using modern │   │   │   ├── javascript-console.rst          |
|                   | IDEs are available on                          │   │   │   ├── mix_bc.png                      |
|                   | eth.org/developers/tutorials                   │   │   │   ├── project-editor.rst              |
|                   | (redirect all pages there)                     │   │   │   ├── scenario-editor.rst             |
|                   |                                                │   │   │   ├── state_mix.png                   |
|                   |                                                │   │   │   ├── state-viewer.rst                |
|                   |                                                │   │   │   ├── transaction-debugger.rst        |
|                   |                                                │   │   │   └── transaction-explorer.rst        |
|                   |                                                │   │   ├── mix.rst                             |
| Sunset            | There is not a lot of specific info on swarm   │   │   └── web3-base-layer-services.rst        |
|                   | on eth.org at the moment, but there is a page  |   |                                           |
|                   | on decentralized storage mentioning swarm      |   |                                           |
|                   | as an option and linking to swarm website.     |   |                                           |
|                   | redirect to /developers/docs/storage           |   |                                           |
|                   |                                                |   |                                           |
| Sunset            | redirect to                                    │   ├── ethereum-clients                        |
|                   | /developers/docs/nodes-and-clients/            │   │   ├── choosing-a-client.rst               |
|                   |                                                |   |   |                                       |
| Sunset            | cpp-ethereum/Aleth no longer maintained        │   │   ├── cpp-ethereum                        |
|                   | redirect whole dir to e.org/deprecated-software│   │   │   ├── architecture.rst                |
|                   |                                                │   │   │   ├── building-from-source            |
|                   |                                                │   │   │   │   ├── android.rst                 |
|                   |                                                │   │   │   │   ├── beaglebone.rst              |
|                   |                                                │   │   │   │   ├── freebsd.rst                 |
|                   |                                                │   │   │   │   ├── index.rst                   |
|                   |                                                │   │   │   │   ├── ios.rst                     |
|                   |                                                │   │   │   │   ├── linux-arch.rst              |
|                   |                                                │   │   │   │   ├── linux-arm.rst               |
|                   |                                                │   │   │   │   ├── linux-fedora.rst            |
|                   |                                                │   │   │   │   ├── linux-opensuse.rst          |
|                   |                                                │   │   │   │   ├── linux.rst                   |
|                   |                                                │   │   │   │   ├── macos.rst                   |
|                   |                                                │   │   │   │   ├── odroid.rst                  |
|                   |                                                │   │   │   │   ├── rpi.rst                     |
|                   |                                                │   │   │   │   ├── wandboard.rst               |
|                   |                                                │   │   │   │   └── windows.rst                 |
|                   |                                                │   │   │   ├── contributing.rst                |
|                   |                                                │   │   │   ├── current-status.rst              |
|                   |                                                │   │   │   ├── index.rst                       |
|                   |                                                │   │   │   ├── installing-binaries             |
|                   |                                                │   │   │   │   ├── docker.rst                  |
|                   |                                                │   │   │   │   ├── index.rst                   |
|                   |                                                │   │   │   │   ├── linux-arch-aur.rst          |
|                   |                                                │   │   │   │   ├── linux-cross-builds.rst      |
|                   |                                                │   │   │   │   ├── linux-mageia.rst            |
|                   |                                                │   │   │   │   ├── linux-sbcs.rst              |
|                   |                                                │   │   │   │   ├── linux-ubuntu-ppa.rst        |
|                   |                                                │   │   │   │   ├── linux-ubuntu-snap.rst       |
|                   |                                                │   │   │   │   ├── osx-homebrew.rst            |
|                   |                                                │   │   │   │   └── windows-chocolatey.rst      |
|                   |                                                │   │   │   ├── portability.rst                 |
|                   |                                                │   │   │   └── running.rst                     |
| Sunset            | Github repo no longer exists                   │   │   ├── ethereumh                           |
|                   | redirect to eth.org/deprecated-software        │   │   │   └── index.rst                       |
|                   |                                                |   |   |                                       |
|                   | Project deprecated                             │   │   ├── ethereumj                           |
|                   | redirect to eth.org/deprecated-software        │   │   │   └── index.rst                       |
|                   |                                                |   |   |                                       |
|                   | Project deprecated                             │   │   ├── ethereumjs-lib                      |
|                   | redirect to eth.org/deprecated-software        |   |   |   └── index.rst                       |
|                   |                                                │   │   │                                       |
|                   | Redirect to geth docs or                       │   │   ├── go-ethereum                         |
|                   | eth.org/developers/docs/nodes-and-clients      │   │   │   └── index.rst                       |
|                   |                                                │   │   ├── index.rst                           |
|                   | Project deprecated                             │   │   ├── parity                              |
|                   | redirect to eth.org/deprecated-software        │   │   │   └── index.rst                       |
|                   |                                                |   |   |                                       |
|                   | Project deprecated                             │   │   ├── pyethapp                            |
|                   | redirect to eth.org/deprecated-software        │   │   │   └── index.rst                       |
|                   |                                                |   |   |                                       |
|                   | Project deprecated                             │   │   └── ruby-ethereum                       |
|                   | redirect to eth.org/deprecated-software        │   │       └── index.rst                       |
|                   |                                                |   |                                           |
| Sunset            | redirect to ethereum.org/en/eth/#main-content  │   ├── ether.rst                               |
|                   |                                                |   |                                           |
| Migrate?          | Some OOD but some really useful info in the    │   ├── frequently-asked-questions              |
|                   | FAQs that is not really covered on eth.org.    │   │   └── frequently-asked-questions.rst      |
|                   | There are FAQs on individual pages but no      |   |                                           |
|                   | central, easily accessible FAQ page. It could  |   |                                           |
|                   | be nice to make one, starting by writing new   |   |                                           |
|                   | answers to these q's. At a minimum some of the |   |                                           |
|                   | info in the answers should be incorporated into|   |                                           |
|                   | relevant pages on eth.org. Then redirect to    |   |                                           |
|                   | e.org homepage??                               |   |                                           |
|                   |                                                |   |                                           |
| Migrate           | Cross-reference against eth.org glossary and   │   ├── glossary.rst                            |
|                   | migrate any not already included. redirect     |   |                                           |
|                   | to e.org/glossary                              |   |                                           |
|                   |                                                |   |                                           |
|                   | redirect to e.org homepage                     │   ├── index.rst                               |
|                   |                                                |   |                                           |
| Sunset            | redirect to e.org/what-is-ethereum/            │   ├── introduction                            |
|                   |                                                |   |   |                                       |
| Sunset            | Mostly OOD. Redirect to                        │   │   ├── community.rst                       |
|                   | https://ethereum.org/en/community/             |   |   |                                       |
|                   |                                                |   |   |                                       |
| Sunset            | Only relevant in context of ethdocs            │   │   ├── contributors.rst                    |
|                   | redirect to e.org homepage?                    |   |   |                                       |
|                   |                                                |   |   |                                       |
| Sunset            | redirect to eth.org                            │   │   ├── foundation.rst                      |
|                   | /foundation/#about-the-ethereum-foundation     |   |   |                                       |
|                   |                                                |   |   |                                       |
| Partial migrate   | redirect to eth.org/                           │   │   ├── history-of-ethereum.rst             |
|                   | /history/#the-history-of-ethereum but flesh out|   |   |                                       |
|                   | the eth.org page with details from here        |   |   |                                       |
|                   |                                                |   |   |                                       |
| Sunset            | Only relevant in context of ethdocs            │   │   ├── how-to-use-this-guide.rst           |
|                   | redirect to e.org homepage?                    |   |   |                                       |
|                   |                                                │   │   ├── index.rst                           |
| Sunset            | redirect to eth.org                            │   │   ├── the-homestead-release.rst           |
|                   | https://ethereum.org/en/history/#homestead     |   |   |                                       |
|                   |                                                |   |   |                                       |
| Sunset            | redirect to eth.org                            │   │   ├── web3.rst                            |
|                   | https://ethereum.org/en/developers/docs/       |   |   |                                       |
|                   | web2-vs-web3/  or new web3 page when deployed  |   |   |                                       |
|                   |                                                |   |   |                                       |
| Sunset            | redirect to                                    │   │   └── what-is-ethereum.rst                |
|                   | https://ethereum.org/en/what-is-ethereum/      |   |                                           |
|                   |                                                |   |                                           |
| Partial Migrate   | combine with material from ethwiki             │   ├── mining.rst                              |
|                   | to bulk out eth.org                            |   |                                           |
|                   | developers/docs/consensus-mechanisms/pow/mining|   |                                           |
|                   | then redirect to that page                     |   |                                           |
|                   |                                                |   |                                           |
| Partial migrate   | in issue #5690 I suggested a new page on the   │   └── network                                 |
|                   | network layer for eth.org. Material here       │       ├── connecting-to-the-network.rst       |
|                   | should be combioned with material from the wiki│       ├── index.rst                           |
|                   | to build that page. Then redirect.             │       └── test-networks.rst                   |
|                   |                                                

Proposed Actions

These are the suggested actions for migrating information and sunsetting obselete pages from ethdocs.org. Each task, if agreed by the ethereum.org team, can be a separate PR to ethereum.org (apart from 6) which will be a PR to ethdocs.org).

1. Expand the json-rpc sections on ethereum.org using updated versions of the material on ethdocs. Currently ethereum.org has a short very high level description and a link to the json-rpc spec, which is not super helpful as an on-ramp. UPDATE: Addressed by PR: Migrate json-rpc information from ethdocs/eth.wiki #5922

2. Build out the Ethereum history page on ethereum.org using details in ethdocs history page. UPDATE: Addressed by PR: migrate Ethereum history page from ethdocs.org #5935

3. Combine mining information from ethdocs with similar material from the wiki and use to bulk out /developers/docs/pow/mining page on ethereum.org UPDATE: addressed by PR: migrate info on pow-mining from ethdocs and eth.wiki #5897

4. Create new "networking layer" page on ethereum.org (as proposed in Migrate materials from eth.wiki #5690) and migrate materials from ethdocs and wiki. UPDATE: Addressed by PR: Add Networking Layer materials to /developers/docs #5838

5. Migrate updated answers to the still-relevant questions in the FAQs on ethdocs and eth.wiki to relevant locations on ethereum.org. UPDATE: now consider this nullified by previous PRs

6. Add deprecated projects from "ethereum-clients" section to ethereum.org/deprecated-software. UPDATE: Addressed by PR: Add deprecated software to "deprecated software" page #5971

7. After PRs 1-5, add 301 redirects to link ethdocs pages to their ethereum.org equivalents as per table above.

Also: The homestead guide github repository also includes an archive of even older material. Do we want to archive it somewhere?

Linked issues

• part of the "Consolidate Ethereum wikis" epic in our Q2 roadmap (Q2 2022 ethereum.org product roadmap #6161)
• related to Migrate materials from eth.wiki #5690
• Change http://ethdocs.org to redirect to wiki homestead-guide#443
• Proposal: migrate content to ethereum.org homestead-guide#473

[samajammin]

Amazing, thanks for taking the time to investigate this & put this proposal together! Overall I think this is a solid plan of action 🤩.

In terms of your specific proposals...

Expand the json-rpc sections on ethereum.org using updated versions of the material on ethdocs. Currently ethereum.org has a short very high level description and a link to the json-rpc spec, which is not super helpful as an on-ramp.

What material on ethdocs are you referring to? I couldn't find much, except a few bits on these pages:

• https://ethdocs.org/en/latest/contracts-and-transactions/accessing-contracts-and-transactions.html#rpc
• https://ethdocs.org/en/latest/connecting-to-clients/index.html

Overall I'm on board with expanding the info we offer on e.org. For context, we previously did list methods, which I'd be in favor of re-adding (context on that here: #3553). One advantage of listing methods directly on e.org is having them available in our site search. I believe the main reason we removed them was fear of maintenance but I don't think this will change all that much - it seems manageable for us to provide.

Migrate updated version of material on Swarm from ethdocs (in combination with similar materials from wiki).

I'm on board with this in terms of expanding info we provide about storage options on https://ethereum.org/en/developers/docs/storage/#related-tools
To be clear, I'd be hesitant to create a dedicated page for Swarm. We tend to shy away from creating pages for specific projects.

Build out the Ethereum history page on ethereum.org using details in ethdocs history page

I support this. We discussed doing something similar in #2919

Combine mining information from ethdocs with similar material from the wiki and use to bulk out /developers/docs/pow/mining page on ethereum.org

I support this 👍

Create new "networking layer" page on ethereum.org (as proposed in #5690) and migrate materials from ethdocs and wiki.

Interesting idea. Where might you see this page living? Perhaps we should consider a dedicated section for protocol developers. I like the idea but it feels fairly advanced & not relevant to a dapp dev.

Create new FAQ page on ethereum.org and add updated answers to the still-relevant questions in the FAQs on ethdocs and eth.wiki.

I'm open to this idea but I'd rather incorporate this Q&As into the relevant pages/topics that we cover on the site rather than create a generic FAQ page that serves as a catch-all for these. Perhaps we could list out the FAQs you're thinking of bringing over & we could try to find a home for them within existing e.org content?

After PRs 1-6, add 301 redirects to link ethdocs pages to their ethereum.org equivalents as per table above.

👍 - I think in addition to adding redirects at the DNS level on ethdocs.org, there'd be a few other final steps, including marking the ethdocs GH repo (https://github.com/ethereum/homestead-guide) as "archived" & updating that README to explain it covered the Homestead release & where to find updated documentation (e.g. currently it mentions https://github.com/ethereum/wiki/wiki which has already been archived).

[samajammin]

Looking at this a bit more in detail, there's a few recommendations I'd change.

Connecting to clients

https://ethdocs.org/en/latest/connecting-to-clients/index.html

• Redirect to https://ethereum.org/en/developers/docs/apis/backend/

https://ethdocs.org/en/latest/connecting-to-clients/web3.js/index.html

• Redirect to https://ethereum.org/en/developers/docs/apis/javascript/

I think the other language-specific subpages you suggested make sense

Contracts and transactions

https://ethdocs.org/en/latest/contracts-and-transactions/developer-tools.html

• Redirect to https://ethereum.org/en/developers/docs/dapps/

Ethereum clients

As you pointed out, many of these projects have been deprecated. I think we should:

1. Add those projects to the deprecated software page
2. Add redirects from those pages to the appropriate section of that page

[jmcook1186]

Thanks for the pointers, @samajammin.

Expand the json-rpc sections on ethereum.org using updated versions of the material on ethdocs. Currently ethereum.org has a short very high level description and a link to the json-rpc spec, which is not super helpful as an on-ramp.

What material on ethdocs are you referring to? I couldn't find much, except a few bits on these pages:

* https://ethdocs.org/en/latest/contracts-and-transactions/accessing-contracts-and-transactions.html#rpc

* https://ethdocs.org/en/latest/connecting-to-clients/index.html

Yes, this is the information I'm referring to. The bulk of the json-rpc information to be migrated over to ethereum.org is actually on the wiki rather than ethdocs. However, I intend to cross reference the information on both sites to make sure nothing useful gets missed.

One thing to note about the json-rpc information is that it might require another round of updates in the not too distant future - the merge readiness checklist shows "update execution-apis" as an as-yet incomplete task. We may also want to include RPC interfaces to consensus clients soon. (I'm considering this as out-of-scope for this issue, but something to remember later).

Overall I'm on board with expanding the info we offer on e.org. For context, we previously did list methods, which I'd be in favor of re-adding (context on that here: #3553). One advantage of listing methods directly on e.org is having them available in our site search. I believe the main reason we removed them was fear of maintenance but I don't think this will change all that much - it seems manageable for us to provide.

Migrate updated version of material on Swarm from ethdocs (in combination with similar materials from wiki).

I'm on board with this in terms of expanding info we provide about storage options on https://ethereum.org/en/developers/docs/storage/#related-tools To be clear, I'd be hesitant to create a dedicated page for Swarm. We tend to shy away from creating pages for specific projects.

ok, this was the consensus from the team call too.

Build out the Ethereum history page on ethereum.org using details in ethdocs history page

I support this. We discussed doing something similar in #2919

Combine mining information from ethdocs with similar material from the wiki and use to bulk out /developers/docs/pow/mining page on ethereum.org

I support this +1

done

Create new "networking layer" page on ethereum.org (as proposed in #5690) and migrate materials from ethdocs and wiki.

Interesting idea. Where might you see this page living? Perhaps we should consider a dedicated section for protocol developers. I like the idea but it feels fairly advanced & not relevant to a dapp dev.

new "networking layer" page with subpages created under developer/docs. Definitely happy to discuss a more suitable home for it as you are right it is not so useful for dapp devs, but very important for protocol devs.

Create new FAQ page on ethereum.org and add updated answers to the still-relevant questions in the FAQs on ethdocs and eth.wiki.

I'm open to this idea but I'd rather incorporate this Q&As into the relevant pages/topics that we cover on the site rather than create a generic FAQ page that serves as a catch-all for these. Perhaps we could list out the FAQs you're thinking of bringing over & we could try to find a home for them within existing e.org content?

ok, makes sense.

After PRs 1-6, add 301 redirects to link ethdocs pages to their ethereum.org equivalents as per table above.

+1 - I think in addition to adding redirects at the DNS level on ethdocs.org, there'd be a few other final steps, including marking the ethdocs GH repo (https://github.com/ethereum/homestead-guide) as "archived" & updating that README to explain it covered the Homestead release & where to find updated documentation (e.g. currently it mentions https://github.com/ethereum/wiki/wiki which has already been archived).

ok, will come back to you to confirm arrangements for this later.

The suggested redirects in the more recent comment have all been updated in the "suggestions" section of the original proposal and an additional PR added for expanding the deprecated software page on ethereum.org.

[jmcook1186]

updated table with specific redirects for each page, taking into account migration PRs

[jmcook1186]

Progress update:

Redirect targets for every ethdocs page have been added to internal EF spreadsheet. Awaiting review for individual PRs before implementing redirects. Otherwise ready to go.

[github-actions]

This issue is stale because it has been open 45 days with no activity.

[samajammin]

This is complete! Content is migrated & redirects are in place. Thank you @jmcook1186 & others for all the hard work!