This guide documents the ENS Labs developer documentation: docs.ens.domains. It contains my assessment of the existing content and opportunities for improvement in two areas:
- API reference documentation.
- Developer guides.
It’s important to clarify the differences between API reference documentation and developer guides.
API reference documentation is designed for developers in need of quick reference materials. They understand how to onboard themselves and interact with the ENS Labs endpoints.
Developer guides (tutorials) help users learn about the ENS Labs platform and endpoints. Often they include example use cases.
ENS Labs API Reference Documentation
The Introduction section on docs.ens.domains is good but requires some work. What’s lacking are how-to developer guides. These are tutorial-based and are published separately from the API reference documentation.
I recommend we rewrite the Introduction section to include links to ENS Labs developer guides training portal. See example: shipengine.github.io/shipengine-openapi/#section/Getting-Started.
Examples of developer guides I’ve written follow for the ShipEngine project I managed in 2019:
With ShipEngine, we hardwired developer guides as top-tier content in their API reference documentation. Doing so allows new users to navigate to the developer training portal from the API reference documentation.
The sidebar navigation of the ENS Labs API documentation can use some upgrading. Specifically by adding sidebar children to the Introduction topic.
At present, the Introduction topic contains the following sub-topics:
I recommend we add child links to ENS Architecture, Namehash, and Getting Started in the sidebar under Introduction. This is an easy fix and will provide users with a simple navigation link to each of these topics. Next, we do the same for all sidebar topics which contain sub-topics in the main content.
See example: stripe.com/docs/api/balance.
I see opportunities to upgrade the API reference documentation content in these areas:
- Build tables for definitions rather than using long bullet lists. See ENS Labs example. See PayPal example.
- Remove the ENS Improvement Proposals from the API reference documentation and move them to the new developer training portal. Some of these proposals are dated making users wonder if they’re still functional. One is noted as obsolete (ENSIP-6: DNS-in-ENS) and shouldn’t be published.
- The Working with ENS page must be moved into the Introduction category as a child page. This is critical reference content new users must be made aware of as they onboard to the ENS Labs platform.
- Add a Developer Guides link in the top header which navigates to the new ENS Labs developer training portal.
The ENS Labs API reference documentation lacks common error examples. After using the search feature, there’s only two reference links to content that don’t appear to be about errors. Great example of error documentation: stripe.com/docs/api/errors.
We need to document all possible errors and include use case examples how to resolve.
Content Style Guide
The ENS Labs API documentation contains a passive voice writing style. Using the active voice writing style offers users bedrock instruction.
What’s the difference?
Active voice instructs rather than suggests multiple options. Active voice avoids predicting (you will) and ambiguous copy (if you’d like). Passive voice offers too many options such as if you want to, can be supported, or if possible.
Below are examples I found of passive voice:
Deploying ENS on a Private Chain (link)
If you’d like to deploy ENS on your own network, or deploy your own copy of ENS on a public network, this guide shows you how. If you want to use an existing ENS deployment, see Resolving Names, Managing Names, and Registering & Renewing Names instead.
We need to upgrade the ENS Labs writing style to maintain content consistency. I’ve been using Google’s developers.google.com/style for nearly a decade. Best of all, it’s free.
I’ve found a handful of different ENS Labs online resources:
We must centralize all of our developer guides to one location: the ENS Labs developer training portal as the one source of truth. Example: shipengine.com/docs. Thereafter, we can syndicate new developer guides online to our social accounts.
Creating case studies helps users learn about the ENS Labs products. They provide users with rich examples and conceptual tutorials which offer the following:
- Product history and usage
- A broad view of the industry
- Launch announcements and updates
- Marketing content to promote adoption
- Specific case studies how to use the ENS Labs platform
We need to pinpoint relevant case studies and write in-depth content to support the developer experience. Then publish them as part of the www.enslabs.org website.
Excellent examples of case studies:
- Case studies category: alchemy.com/case-studies.
- FAQ case study: alchemy.com/case-studies/treasure.
- Marketing case study: alchemy.com/case-studies/kyber-network.
- Launch case study: alchemy.com/case-studies/zapper.
- Self-promotion case study: alchemy.com/case-studies/0x.
Clear, concise UX writing requires helping users take action. It’s a content strategy designed to guide users down a happy path learning about products and offers. As a new user to the ENS Labs platform, I don’t see any calls-to-action to take the next step. Best-in-class UX writing instructs users to make a decision to learn more.
We need to identify the top products ENS Labs wants new users to learn about during their journey. Then integrate UX buttons throughout our developer guides and website content to promote these products. Below are examples I recommend we consider integrating into our content:
- Get your Free DNS Domain
- Beginner’s Guide to Ethereum and ENS Labs
- The Insider’s Guide to Blockchain Naming Standards
Alchemy.com Use Case
During my time working with Alchemy.com, one of my tasks was to help them generate more users. I initiated the use of a block of code at the top of select pages offering users to Get started for free. See it live: alchemy.com/reference/api-overview.
An obvious way to help users onboard is to grow the ENS Labs channel: youtube.com/@ENSdomains/videos. After reviewing your channel, it appears most of the videos are from 2 years ago.
My experience producing videos and marketing them on YouTube is vast. The benefit of simple instructional videos is they helps users understand ENS Labs concepts. When you combine the free reach of YouTube with the value of walking users through the ENS Labs platform, you generate interest and adoption.
Publishing videos is a commitment of developer time while balancing long shelf life content. To solve these challenges, I recommend we develop a short template for YouTube videos. Topics should include high-level introductory content such as FAQs (1 per video) and developer guides. These videos must be short: between 3-5 minutes long with a focus on one concept per video. Our goal should be to publish 1-2 new videos a week on YouTube.
Examples of best-in-class videos are below:
Search Engine Marketing
Blog marketing generates free traffic. As we begin writing new blog posts, I strongly urge us to optimize each post for relevant keywords related to ENS Labs.
The process is easy provided we track organic traffic and search engine rankings using a tool such as SEMRush.com. Recently, SEMRush has also launched YouTube analytics.
Search engine marketing must be hardwired in all of our marketing efforts (blogs and YouTube videos). Between 2007 and 2012, I consulting clients how to improve their Google and YouTube rankings. Creating search engine-optimized content is an easy process. But it must be tactical and embedded in our content creation workflow.