Readthroughs and user testing

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.

Readthrough notes no. 1

Notes from my readthrough with Mako.

Background

• 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.
• Concepts already familiar with: public/private keys, base64, hashes, protocol buffers, TCP and UDP.
• Reading How Dat Works for the first time.
• 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?
• Plain-language explanation of DNS exchange: this style is helpful for understanding.
• What is the token for? Is it to distinguish simultaneous request/response pairs. Isn’t this over TCP which does that for you?
• In what case would the server ever need to send more than 31 peers?

After an hour we had just started reading the wire protocol section. Had a quick browse through the rest to see what was there.

Overall thoughts

• Suggest to have a table of contents or index with a brief description next to each heading to help find interesting bits.
• For each message type, repeat the plain language description (“I want to talk to you about this particular Dat”) in the section that describes it.
• Future of Dat: good to have this section present.
• Why is the files and folders section present? Are files and folders a fundamental part of the protocol?
• Probably would have scrolled around more to find interesting sections first if reading alone.
• Overall good impression of the guide, felt minimally confused while reading.

Readthrough notes no. 2

Notes from my readthrough with Phil.

Background

• 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.
• Would be good to include HyperDB.