Dat documentation [ DEPRECATED - see https://github.com/hypercore-protocol/new-website/tree/master/guides for similar functionality. More info on active projects and modules at https://dat-ecosystem.org/ ]
Found Dat via Rotonde, later became interested in Dat itself.
Found How Dat Works via a link being shared on local Mastodon instance.
Have previously done programming and read other technical documentation.
Interested in How Dat Works to see what the protocol is capable of, identify limitations (which are not typically mentioned on a project’s homepage). Want to find out what parts would be easy to change vs. which parts are set in stone.
Checked out support for Dat in Firefox and Brave but there were too many steps to install the extension.
Would normally read this guide on a desktop computer.
Opening thoughts
How does Dat compare to IPFS? Initial thought is Dat supports mutating data whereas IPFS is immutable.
Does Dat support censorship resistance? (Not included in list of strengths.)
URLs section
What is ed25519?
How many bytes are in the hexadecimal part of the URL?
Discovery section
Is is possible for Dat to work in a way that does not reveal IP addresses?
Suggest to introduce each discovery method with numbering such as: “Discovery method 1: Local network discovery”.
Clicked though to Paul’s Hyperswarm blog post and read before continuing (“interesting, good to know”).
Length-prefixed strings in DNS figures: Is each string part of the same section or different? Suggest putting “dat” and “local” parts on separate lines.
Already seen Protocol Buffers and recognized the concept of length-prefix strings from there.
“Essentially the computer is asking…” part was clarifying and suggest to put earlier.
Why base64 encode IP addresses in the peers record? Why not just use raw bytes?
Multi-byte numbers: confusion over the purpose. Could it be for error correction?
mDNS discovery: Is there an example showing a response?
Needed a peer-to-peer framework for a project, searched around, found Dat.
Dat worked first time unlike other tools tried. Also drawn in by Dat being run by a non-profit, community driven.
Background as both a designer and developer.
Reading How Dat Works for the first time.
Reading on a laptop (Chrome, macOS).
Introduction section
First paragraph could use a bulleted list rather than a long sentence with lots of commas.
User experience and ease-of-use are the same thing.
Consider adding a sentence like “This will give you all the conceptual info to write your own clients” or “You could get a basic Dat client built in the weekend” for example.
Needed a high level summary before diving into details in the next section.
URLs section
What is Beaker? Could include a brief aside.
What is ed25519? Why is it significant? What properties does it have that meant it was chosen?
“and is also verify” typo.
Make note that public key sharing in URLs is a user experience feature. Sharing keys is a pain point in other protocols.
Ambiguous use of the word Dat from introduction section.
Discovery section
Why are discovery keys needed, e.g. “Discovery keys are a security mechanism…”
Frame the hashing process as a balance between security (from eavesdropping) and ease of use.
Haven’t properly introduced public keys yet but already talking about discovery keys.
The sentence “Calculate a Dat’s discovery key using…” is an abrupt switch from explaining to issuing instructions. Make clear that the guide is not actually asking readers to perform this task themselves.
Local network discovery section
Strengths, weaknesses, deployment status bullet points useful.
“Physically nearby peers” — consider rewording.
Client asking for peers diagram: which fields are DNS-specific, which are Dat-specific? What are the important parts to glean from this, will this information be necessary to me?
Centralized DNS discovery section
Show the contrast between centralized DNS and local network discovery.
Wire protocol section
Bit notation: What makes the most significant bits most significant? Why are the rightmost fields fixed-length but the leftmost field not?
How do the message types 1–15 fit into the 4 slots of the message type field?
Want and have section
When describing have messages, call out the word “have” with quotes, italic etc.
Overall thoughts
Needed a high level overview of all the concepts/modules/pieces before diving into details. Transition from introduction to low level implementation details was jarring.
Each section could use more explanation of why it was done that way.
Do a couple of in-person readthroughs with first time readers to find sticking points.
Also consider doing a few via video call to see if that will be another effective medium for user testing.