How Dat Works: New documentation for the Dat protocol

How Dat Works is a new guide that explains how computers running Dat communicate with each other to share files. Today is the first release of this documentation and we’re looking for new readers and feedback!

Screenshot of How Dat Works

How Dat Works is focused on explanation and being accessible to a wide variety of readers, including newcomers who just want to get the gist of what’s going on behind the scenes of Dat. However, there is also enough detail for implementers to find out exactly what bytes they need to send over the network to make a compatible implementation.

The most visible aspect of this is the pictures. By area, How Dat Works is three-quarters pictures and one quarter text.

Figure showing a bird’s-eye view of the guide with pictures and text highlighted in different colors

Where text is used I’ve tried to keep the language as simple as possible. Concepts are introduced throughout the guide as they are needed in order to keep it readable from start to end. Almost every concept is introduced with an example or by showing it in context. Visual aspects such as layout, alignment, whitespace, repetition and color are underused in technical documentation so How Dat Works makes heavy use of these.

Dat is reaching a point where people are experimenting with posting their writing, art, music and personal websites on it. As more experimentation happens and more people post their work on Dat, it becomes compelling for multiple implementations of the protocol to exist. Dat was originally written in JavaScript and now the community is also working on a Rust implementation.

I hope that with How Dat Works being available, people considering writing new implementations will have an easier time understanding the steps to make that happen. How Dat Works is programming-language agnostic and currently doesn’t contain a single line of code, but instead shows the structures and algorithms that are necessary regardless of programming language. Source code can still be useful to get another perspective and dig into details, so the guide also has links to implementations throughout it for readers who are interested.

I’d like to thank Mozilla for funding this work and the Dat community for supporting it, through the Mozilla Open Source Support grant to Dat. It’s not often that open source projects get funding for full-time documentation writers. I’d also like to thank the Dat Project for being willing to take a risk and try out a radically different style of technical documentation like this. There is still a huge space to explore with respect to documenting computer programs and protocols. It does take time and effort, but I think it’s worthwhile to make internet infrastructure understandable for people who use it but don’t happen to be programmers.

Being the first release of this documentation there will be snagging points and parts that could be explained better. I’m relying on reader feedback to find out where these are. Have a read and tell me which parts you found confusing so that I can improve them. Thanks and please enjoy!

(Cover art is a derivative of Ben Simonds’ Jungle Temple from Blender Master Class)