Missing Content, Unresolved TODOs, and Clarity Improvements Needed in ENS Documentation

[Entropizm]

Missing Content, Unresolved TODOs, and Clarity Improvements Needed in ENS Documentation

#Team: IntroGram

Description

While reviewing the ENS documentation, I've noticed several pages that contain unresolved TODO comments, missing content, and areas that could be clarified further. These issues make some topics confusing and incomplete, which could hinder developers trying to build on ENS. Below are the specific pages and sections that need attention:

1. DNS on ENS Page

• File Path: /dns/dns-on-ens.mdx

• Issue:
  There's a TODO comment indicating the need for a user-friendly explanation about how DNS names work within the ENS system.

  <> 
    {/* TODO: User-friendly explanation of the fact that DNS names also work in the ENS system. */}
  </>

• Suggestion:
  Add a clear, beginner-friendly explanation of how DNS names can be integrated with ENS. This should cover the basics of DNS integration, the benefits of using DNS names on ENS, and how they differ from .eth names.
  Explain the process of importing DNS names into ENS, possibly with step-by-step guidelines or a simplified overview.

2. Top-Level Domains Section

• File Path: /dns/dns-on-ens.mdx

• Issue:
  There's a TODO comment mentioning the need to insert examples of TLDs like protocol.art, .kred, etc.

  <>
    {/* TODO: Insert examples of protocol.art, .kred, etc. */}
  </>

• Suggestion:
  Provide real-world examples of existing TLDs that have integrated with ENS. Discuss how these TLDs have leveraged ENS, any specific benefits they've experienced, and perhaps include links to case studies or additional resources. Including these examples will help users understand the practical applications of integrating TLDs with ENS.

3. Layer 2 & Offchain Resolution Page

• File Path: /learn/layer-2-offchain.mdx

• Issue:
  There's a commented-out section regarding "Primary Names on Layer 2" with a note that it's under active development.

  {/*
    ## Primary Names on Layer 2
    The process of storing primary names on Layer 2 is still under active development, and more updates will be posted here as they become available.
    <WIP />
  */}

• Suggestion:
  If there's any new information or updates on supporting Primary Names on Layer 2, it would be beneficial to include it here. If development is still in progress, consider providing an estimated timeline or directing users to where they can find future updates.

  Alternatively, you can uncomment this section and add a disclaimer about it being a work-in-progress (perhaps using a <Note> component) to inform users that the feature is forthcoming.

4. ENS Improvement Proposals Page

• File Path: /ensip/index.mdx

• Issue:
  There's a commented-out section under "Propose an ENSIP" mentioning a missing guide on how to propose an ENSIP.

  {/*
    ## Propose an ENSIP
    Feel free to [open a GitHub issue](https://github.com/ensdomains/docs) or pull request on [ensdomains/docs](https://github.com/ensdomains/docs).
    <WIP missing={["How to propose an ENSIP"]} />
  */}

• Suggestion:
  Provide a section or a link to documentation that guides users on how to propose a new ENS Improvement Proposal. This could include guidelines on the proposal process, formatting requirements, review procedures, and where to submit proposals.

5. Improve Clarity on the "Interacting with a Resolver" Documentation Page

• File Path: /resolvers/interacting.mdx

• Issues:

  • Insufficient Explanation of Records:
    The section on updating a user's record does not clearly explain the types of records available (e.g., text records, address records) and how they are used.
  • Missing Guidance on Resolver Addresses:
    There is no guidance on how to find or set the resolver address for a name, which is crucial for interacting with the resolver.

• Suggestions:

  • Provide Comprehensive Examples:
    Add step-by-step tutorials on how to interact with resolvers, including setting and retrieving different types of records.
  • Include a Table of Record Types:
    Provide a table or list of common record types with explanations and examples of when and why they are used.
  • Explain How to Work with Resolver Addresses:
    Add a section explaining how to obtain a resolver address from a name and how to set a resolver if one is not already set.
  • Offer Best Practices:
    Include guidelines on how to safely update resolver records, including handling user permissions and security considerations.
  • Add Troubleshooting Tips:
    Share common pitfalls and how to avoid them when working with resolvers.
  • Provide Additional Resources:
    Link to example projects, repositories, or community tools that demonstrate resolver interactions.

Reference:

• Page Title: Interacting with a Resolver
• Page URL: Interacting with a Resolver Documentation