Supplement IPFS concepts with diagrams.

[kvutien]

I'm reading the explanations on https://docs.ipfs.io/concepts/how-ipfs-works/#distributed-hash-tables-dhts and I find it a bit hard to follow. Maybe it's not quite a "IPFS 101" because you assume the reader is not a beginner? https://en.wikipedia.org/wiki/101_(topic)

Until the Merkle DAG I could more or less understand because I've been exposed to Ethereum's Merkle trees, but even here a diagram could help.

Then from the DHT I was kind of lost. What are the blocks? what kind of key-values pairs? And how the connection multiplexing works?

I don't know how your average reader thinks, I'd suggest a liberal use of diagrams here.

[welcome[bot]]

Thank you for submitting your first issue to this repository! A maintainer will be here shortly to triage and review. In the meantime, please double-check that you have provided all the necessary information to make this process easy! Any information that can help save additiona round trips is useful! We currently aim to give initial feedback within two business days. If this does not happen, feel free to leave a comment. Please keep an eye on how this issue will be labeled, as labels give an overview of priorities, assignments and additional actions requested by the maintainers:

• "Priority" labels will show how urgent this is for the team.
• "Status" labels will show if this is ready to be worked on, blocked, or in progress.
• "Need" labels will indicate if additional input or analysis is required.

Finally, remember to use https://discuss.ipfs.io if you just need general support.

[johnnymatthews]

This is a fair point. There currently aren't any designers/illustrators on the IPFS docs team, and as such, we've relied pretty heavily on words to explain and educate. However, adding a few diagrams through the docs will hugely improve things, especially within the concepts section. What we should do here is define exactly which concepts need diagrams and what those diagrams should illustrate.

@kvutien, you've already mentioned that adding some illustrations for block, key-value pairs, and connection multiplexing would help. Are there any other sections or concepts you came across that you think could do with some illustrations?

[kvutien]

Are there any other sections or concepts you came across that you think could do with some illustrations? ...

Thank you for the indulgent reply. I'm just starting to get acquainted with IPFS for a #tech4good project named Machu Picchu so this page is my first contact. This is why I contributed this remark because it's a reaction from someone really fresh in the domain, and eager to learn.

If you want, I could try and share a set of Google slides with you, containing some tentative diagrams how I understood the explanations, for you to amend and add in the 101.

There are probably many other sections that might take advantage of diagrams, but for sure, a section named "101" would be largely benefit from them, to handhold the newcomer. I'll continue reading and let you know.

To digress a little bit from the topic, here is an explanation of Machu Picchu, to hint why IPFS would be the core tool for Machu Picchu: https://youtu.be/9fWTD8gf-Us and here is the same in text-only form https://kvutien-yes.medium.com/machu-picchu-how-the-blockchain-can-help-persons-in-need-8396820d13d1. I've spent some time helping humanitarians. They favor operations and IT (Information techno) is not their main focus. However, IMHO they would benefit tremendously from the new technologies.

[johnnymatthews]

I could try and share a set of Google slides with you - @kvutien

That would be incredibly useful, thanks!

Machu Picchu sounds like an interesting project! No doubt we'll hear more about it in the future.

[kvutien]

Something like this? https://docs.google.com/presentation/d/1BwmFejXzTJ0O3PscuXdKk44ldyOUlGXV0rTuIddCgKE/edit?usp=sharing

[kvutien]

In the meantime, I'm starting the ProtoSchool tutorials. They are incredibly helpful to understand IPFS and the underlying concepts.

1. Maybe a quick fix for this IPFS 101 page is to add a section on IPLD before going in down into Merkle trees and DHT? What do you think?

2. IMHO what confuses me as a beginner is that the IPFS team is a decentralised team: everyone is free to write what he/she thinks that could be useful but there is no technical editor who has authority to coordinate the style and the contents among all the posts. Some contents are amazing and some are somewhat obscure.

3. BTW, you may be interested to know that the first 4 links of this intro page of this doc github are broken? Same for [this README](https://github.com/ipfs/ipfs-docs/blob/main/docs/how-to/README.md. I volunteer to chase the links and do a PR. I'm interested to read and learn so anyhow i'll fork the repo and do the corrections for my own use. If it can be useful to other people, it's just as good.

[2color]

I stumbled upon this issue and thought it might be useful to share this interactive visualisation that explains Kademilia: https://kelseyc18.github.io/kademlia_vis/basics/1/

[salmad3]

We started a unified graphics initiative for libp2p in collaboration with Crcle: https://github.com/libp2p/docs/issues/206. This can be scaled to IPFS content (and beyond) once ready.