Viem documentation is typical of crypto projects and we can all do better

[lukepuplett]

Around 80% of crypto and blockchain API and SDK projects, apps and services have extremely poor documentation. We need to seriously up our game if we ever want crypto curious developers to begin integrating blockchain functionality into offchain products.

Take the following page for example. It raises more questions than it answers. It literally creates more work for the reader. It's like a bad employee who takes from those around, or a bad team mate who throws bad balls.

https://viem.sh/account-abstraction/accounts/webauthn/createWebAuthnCredential

I criticised the page heavily and asked an LLM to rewrite it as if it wasn't egocentric, but had great empathy for the reader, their knowledge and to anticipate questions.

It has done a brilliant job. This was 60 seconds work. This should be the level of our documentation in the era of AI. There is no excuse. We must also make self-documenting SDK surfaces and be very careful over our naming, esp. around functions which cause serious effects, such as writing (to a blockchain, etc.) or which block for user input.

That said, I suspect if I'd put in a PR for all these changes, status quo bias would kick in and it'd be rejected.

Here's the page again (code snippets, mostly removed):

createWebAuthnCredential

Overview

createWebAuthnCredential initiates the WebAuthn registration flow on the user's device, creating a cryptographic credential (commonly called a "passkey") that can later be used for authentication. The function handles the browser's credential creation dialog and returns a credential object that you can store and use to create WebAuthn accounts.

Think of this as the registration step—it's what happens when a user first sets up their passkey on your application.

What This Function Does

When you call createWebAuthnCredential, it:

1. Triggers your browser's built-in credential creation dialog (the interface where users confirm they want to create a passkey)
2. Communicates with your device's authenticator (fingerprint sensor, Face ID, security key, etc.)
3. Generates a cryptographic key pair on the device
4. Returns a credential object containing the public key and metadata
5. Never sends the private key off the device—it stays secure

When to Use It

Use this function during your application's account registration or passkey setup flow. It's a one-time operation per device—once a user creates a credential, you store it and use it for subsequent authentication attempts.

Basic Usage

At minimum, you need to provide a name to identify the credential:

const credential = await createWebAuthnCredential({
  name: 'My Passkey',
})

The function returns a P256Credential object that you can then pass to toWebAuthnAccount() to create an account, or store in your database for later use.

Parameters Explained

name (required)
A user-friendly display name for the credential. This appears in your browser's credential manager and helps users identify which passkey they're using. Use something descriptive like "My Laptop Fingerprint" or "Security Key".

challenge (optional)
A random cryptographic value that proves this credential creation request came from you and not an attacker. If you don't provide one, the function generates a random one. For production applications, you should generate a challenge on your server and send it to the client to prevent replay attacks. It must be a Uint8Array.

rp (optional, but recommended for production)
An object describing your relying party (your application). Contains:

• id: Your domain (e.g., "example.com"). This ties the credential to your domain, preventing the credential from being used on other sites
• name: Your application name (e.g., "Example App")

Without this, the function uses sensible defaults, but explicitly setting it is more secure and explicitly shows your application name to the user during registration.

timeout (optional)
How long (in milliseconds) to wait for the user to complete the registration before giving up. The default is usually sufficient. Set this if you expect slow network connections or users who take longer to interact with their authenticators.

excludeCredentialIds (optional)
An array of credential IDs you want to prevent from being re-registered. If a user already has a credential with one of these IDs on their device, the registration will fail. Use this to prevent duplicate credentials and ensure each device can only register once.

createFn (optional, advanced)
Allows you to override the default credential creation function. By default, it uses window.navigator.credentials.create, which is the standard WebAuthn API. Override this only if you're in an environment that doesn't support WebAuthn natively (React Native, test environments, etc.). Pass a custom function that accepts the same options and returns a credential or null.

What You Get Back

The function returns a P256Credential object containing:

• The public key (safe to store and transmit)
• Credential metadata
• Information needed to verify the user later during authentication

Error Cases to Handle

The registration can fail or be cancelled for several reasons:

• The user cancels the credential creation dialog
• The device doesn't support WebAuthn
• The credential already exists (if using excludeCredentialIds)
• The timeout expires while waiting for user interaction
• The authenticator is locked or unavailable

Wrap the function call in a try-catch block to handle these gracefully.

Next Steps

Once you have a credential, use toWebAuthnAccount() to convert it into a usable account object, then store it in your database or session for future authentication attempts.

[jxom]

That said, I suspect if I'd put in a PR for all these changes, status quo bias would kick in and it'd be rejected.

Why is that your assumption?

[lukepuplett]

It's a big, slightly offensive, suspicion!

You see, the current docs are so lacking in explanatory depth, in a prevailing context where quality explanations costs nothing more than an LLM call, that one charitable assumption is that it's an editorial decision and reflects a documentation design philosophy I am ignorant of.

Hence my coming here to test the waters (rather than waste the ceremony of a PR), but also to draw attention to the importance of warm and welcoming docs in a space which is derided by the very people we want to start building on blockchain!

Crypto is very blokey and reminds me of working on trade-floors. It's like the TV series Industry. It's cold and guarded, side-eyes, and we often design our websites in dark, macho colours. Perhaps it's because we do have to be guarded and slightly suss.

AI, on the other hand, feels more open and friendly. One website is branded around a big, hugging emoji logo 🤗

I'm not messing around. I feel it daily in the docs pages of various crypto projects. We need to say, "Hey! Come on in, I'll show you around. Are you from North Korea? Nope. Oh, no reason. I love your hair."