Status update on the implementation book:
We've also conducted a general survey of existing DEPs. This was useful to use as a reference when writing the docs, but also to point out some of the gaps in the existing deps. We're currently considering a few possible DEPs, but are very much prioritizing the guide first.
Here is an update on the documentation I am working on:
Next I am going to look into replication strategy and show examples of peers exchanging data about a hypercore feed. I am working towards showing how to download or share files using hyperdrive.
So far I have been trying to cover some breadth and am planning to revisit for depth, polish and consistency.
I’m almost halfway through the time I have dedicated to work on documentation. Here’s an update on where I’m heading.
So far I have covered:
The two big topics I plan to add in the following weeks are:
And then spend the rest of the time on polish, checking correctness, improvements in response to feedback and consistency.
Currently I don’t think these topics will make the cut, but this will depend on timing:
Combining with other docs
I’m just starting to reach what is already covered in the Dat Protocol Book, so I’ve been thinking about which of these docs it will make sense to merge into and how it will integrate with datproject.org / datprotocol.com.
I think that there is enough difference between the styles and target readers of these different docs that they will each be able to stand on their own. For example, the docs I am working on have a strong focus on explanation without offering much guidance on implementation and the Dat Protocol Book has a strong focus on implementation and offers guidance on ways to structure code.
I’m still open to later merging my work into another place if people think that will help keep Dat’s docs cohesive, but I’m going to keep working just in an HTML file for now and we can figure out where a good place to host it will be.
Finally on naming, I saw that @joehand described what I am working on as “How Dat works”. I really like the name and think it lines up with what I’m trying to do so I’ll rename it to that soon!
(edit: I’ve done the rename now and updated the links above to point to the new location)
Progress update on How Dat Works
I’ve got two weeks left of the time I have dedicated to working on these docs, so I’m planning and working towards a v1 Release. The idea is to generate a bit of excitement and enthusiasm about releasing these new docs. The date I have planned is 22 Jan 2019, two weeks away.
Here is my list of things I’ll be working on to get ready for the release. Mostly it’s polish and improving the quality of the docs with a few gaps to fill in about the protocol.
My plan for the release itself is:
One goal I have for the release is to gather feedback from new readers and find some people willing to do a readthrough with me. When I’ve done this kind of user testing in the past it has been very time intensive but also hugely improved the quality. So I think it’s worth it but not something that I’ll be able to make happen before v1.
There’s still lots that could be improved with the guide beyond the fixes that I’ll be spending the next two weeks on, but I think this will be a good start.
@joehand Sure thing!
I've read and reviewed all DEPs, and pre-draft DEPS. Not all (pre-)drafts seemed to be in a state where feedback would be useful, so I refrained from providing feedback on some of them. The following changes were landed on the DEPs repository:
How Dat Works published!
Blog post here: How Dat Works: New documentation for the Dat protocol
My plans for the next while are mostly listening to feedback and working in any easy/high impact changes and fixing any mistakes that I find.
Special thanks to @joehand for organizing this, kicking it off, helping me out and making it a fun process!