search

dat-ecosystem-archive / how-dat-works

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/ ]
https://dat-ecosystem-archive.github.io/how-dat-works/
169 stars 9 forks source link

Clarification of hex and decimal #2

Closed dariusk closed 5 years ago

dariusk commented 5 years ago

(Hi! I'm working with Code for Science & Society as their Mozilla Fellow so I'm reading through this doc and thought I'd put notes on it here as I'm trying to learn the protocol. REALLY great job overall btw.)

I notice that you are choosing to show decimal representation of individual bytes rather than their hex, which mostly makes things very clear. However there are some parts where multiple bytes act as 16-bit word and suddenly it gets confusing. For example, this image confused me:

image

I didn't realize that 12 210 was just the decimal readout of 0c d2. I was like, is that octal? Base 3? What's going on? Basically the connection between 12 210 and 3282 is unclear. If the image said 0c d2 instead that would be instantly clear but then it would conflict with everything else you have going on in the document.

Maybe annotate the image like so?

image

I would have made a PR but then I realized that you do have a style going so I thought I'd pose this as more of a question.

ghost commented 5 years ago

Thanks, this is a really clear explanation of why this is confusing! Awesome feedback!

I’m going to try adding an aside to explain this the first time it appears, similar to the concept you have drawn.

ghost commented 5 years ago

Ok, I’ve added these three asides to explain the decimal notation as each new concept is needed.

aside_1

aside_2

aside_3

@dariusk, Do you think these would have helped you understand this more easily on your first read through? Is there anything you would add or change?

dariusk commented 5 years ago

Yes that is great and fully addresses my issue!

Since I've been thinking about it there is only other thing I would ask for. In the following representation of an IP address:

image

it might make more sense if there were a . between the numbers. So it would look something like [0].[0].[0].[0]. Just to be clear that each byte represents one of the 4 fields in the IP address. But maybe that is too nitpicky and people can figure that out from context.

ghost commented 5 years ago

Great! I’ll try out the IP address formatting suggestion and include that too if works ok visually.