I love ENS! It has pioneered and simplified several aspects of the blockchain space, especially transactions. The first sentence of the first page of the ENS docs starts with jargon. You want everyone who opens the docs to know exactly what ENS is without jargon. For example: “Have you seen a crypto wallet address before? They’re typically a long series of letters and numbers. The anxiety of making sure you type your correct wallet each time is notttt it! So ENS created a solution which is essentially a username for your web3 wallet address so rather than copying and pasting (or typing if that’s your flex 👀?” - throw in a little Gen Z terminology if need be too! Inspire the future leaders and current CS students to build build build from now.
Although most blockchain developers should know what ENS is, statements like ‘The Ethereum Name Service (ENS) is a distributed, open, and extensible naming system based on the Ethereum blockchain, but available to the entire internet.’ might be new to web2 developers and sometimes all it takes is one clear opening statement to engage a new crowd. Equally, all it takes is one sentence for a dev to click off of a page - we don’t want that! It's great that you have a Terminology page but it comes much later and still has jargon.
Also the imagery used in the first page of the docs is useful but I’d actually suggest changing the order of the following:
The long wallet address should be first followed by the arrow pointing to nick.ens - reason being, is you're showing exactly what ENS does this way! It simplifies long web3 wallet addresses to digestible usernames (plus many other things!). You do this well on the second tab (Using ENS) of the docs:
Another suggestion is that they key tabs are on the top, I'd suggest making this clear by highlighting the background with a different colour (not just the text itself) so not only do users know that they should click on Using ENS ➡️ Smart Contracts ➡️Governance ➡️ Improvement Proposals
Furthermore, the 'Quickstart' should be much earlier than it is now. Sometimes, as devs, what we want to see is the Quickstart immediately! The docs can start with a jargon-free one liner followed by a Quickstart and as each tab and page progresses, the reader is learning about ENS more and more - it keeps everyone engaged!
There is also some duplication across 'Tools and Libraries' and the Quickstart - so more the reason for the Quickstart to be much earlier on, and even lead the documentation! Additionally, the Quickstart says "If you want to learn the process checkout everything about ENS in dApps" however, the 'everything about ENS in dApps' just links back to 'Getting Started' - if anything, I would link it back to a page that has an H1 title of literally 'everything about ENS in dApps'. You have the following at the end of the page but it means people are just going back in circles:
Now, do you want to assume everyone has "a basic understanding of react, ethers, wagmi, tailwindcss, and web3" or do you want to give them a quick 101? Back to the title of this issue "Onboarding web2 devs by rewording aspects of the docs" and the opening paragraph, sometimes that tiny extra bit of effort is the difference between someone clicking off and someone staying on and building!
At the end of the Quickstart page, it's probably best to signpost people to the discord/dev support:
So adding the following sentence: Still not sure? Don't worry, we're here to help! For more information, join our Discord and find Greg on TG/Twitter! You should also join our developers telegram group.
About the issue-author 😎
Hey! I'm Adaku, the president of the Oxford University Blockchain Society - I have 4 degrees, including a PhD and I'm doing a Postdoc at Oxford University too. It's safe to say I've seen my fair share of documents haha and education is key to everything I do! I have taught technical and non-technical workshops too and what I find it that, the easier and jargon-free you make the onset of the workshops/docs, the higher the likelihood that the readers/viewers/attendees will stay and engage. People want to learn but sometimes there's a particularly moment where they're lost but too shy to ask, and that's the point where you lose them - this is preventable! You want everything to be so digestible that people have no choice but to build immediately, and with confidence, and with a subsequent smile! With great docs (and videos if possible), you can change the world! LITERALLY.
I love ENS! It has pioneered and simplified several aspects of the blockchain space, especially transactions. The first sentence of the first page of the ENS docs starts with jargon. You want everyone who opens the docs to know exactly what ENS is without jargon. For example: “Have you seen a crypto wallet address before? They’re typically a long series of letters and numbers. The anxiety of making sure you type your correct wallet each time is notttt it! So ENS created a solution which is essentially a username for your web3 wallet address so rather than copying and pasting (or typing if that’s your flex 👀?” - throw in a little Gen Z terminology if need be too! Inspire the future leaders and current CS students to build build build from now.
Although most blockchain developers should know what ENS is, statements like ‘The Ethereum Name Service (ENS) is a distributed, open, and extensible naming system based on the Ethereum blockchain, but available to the entire internet.’ might be new to web2 developers and sometimes all it takes is one clear opening statement to engage a new crowd. Equally, all it takes is one sentence for a dev to click off of a page - we don’t want that! It's great that you have a Terminology page but it comes much later and still has jargon.
Also the imagery used in the first page of the docs is useful but I’d actually suggest changing the order of the following:
The long wallet address should be first followed by the arrow pointing to nick.ens - reason being, is you're showing exactly what ENS does this way! It simplifies long web3 wallet addresses to digestible usernames (plus many other things!). You do this well on the second tab (Using ENS) of the docs:
Another suggestion is that they key tabs are on the top, I'd suggest making this clear by highlighting the background with a different colour (not just the text itself) so not only do users know that they should click on Using ENS ➡️ Smart Contracts ➡️Governance ➡️ Improvement Proposals
Furthermore, the 'Quickstart' should be much earlier than it is now. Sometimes, as devs, what we want to see is the Quickstart immediately! The docs can start with a jargon-free one liner followed by a Quickstart and as each tab and page progresses, the reader is learning about ENS more and more - it keeps everyone engaged!
There is also some duplication across 'Tools and Libraries' and the Quickstart - so more the reason for the Quickstart to be much earlier on, and even lead the documentation! Additionally, the Quickstart says "If you want to learn the process checkout everything about ENS in dApps" however, the 'everything about ENS in dApps' just links back to 'Getting Started' - if anything, I would link it back to a page that has an H1 title of literally 'everything about ENS in dApps'. You have the following at the end of the page but it means people are just going back in circles:
Now, do you want to assume everyone has "a basic understanding of react, ethers, wagmi, tailwindcss, and web3" or do you want to give them a quick 101? Back to the title of this issue "Onboarding web2 devs by rewording aspects of the docs" and the opening paragraph, sometimes that tiny extra bit of effort is the difference between someone clicking off and someone staying on and building!
At the end of the Quickstart page, it's probably best to signpost people to the discord/dev support:
So adding the following sentence: Still not sure? Don't worry, we're here to help! For more information, join our Discord and find Greg on TG/Twitter! You should also join our developers telegram group.
About the issue-author 😎 Hey! I'm Adaku, the president of the Oxford University Blockchain Society - I have 4 degrees, including a PhD and I'm doing a Postdoc at Oxford University too. It's safe to say I've seen my fair share of documents haha and education is key to everything I do! I have taught technical and non-technical workshops too and what I find it that, the easier and jargon-free you make the onset of the workshops/docs, the higher the likelihood that the readers/viewers/attendees will stay and engage. People want to learn but sometimes there's a particularly moment where they're lost but too shy to ask, and that's the point where you lose them - this is preventable! You want everything to be so digestible that people have no choice but to build immediately, and with confidence, and with a subsequent smile! With great docs (and videos if possible), you can change the world! LITERALLY.