IPFS onboarding feedback

[fsdiogo]

Hey guys, I'm pretty new to IPFS and @diasdavid said it would be helpful to give some feedback about the onboarding process, so here it goes:

• I've watched a bunch of talks by Juan about IPFS and they were a great intro to IPFS
  • The alpha demo is pretty cool to get a quick overview of some of the things you can accomplish with IPFS
  • This talk at Stanford was great to understand the motivations behind the IPFS project
• Almost all of the talks that gave an overview of IPFS were pretty long (1-2 hours)
  • Having a shorter video explaining IPFS and its layers would be cool, because a lot of people will be put off by the length of the ones out there
  • I also understand that due to the complexity of the project, it may not be possible to do that!
• The IPFS specs are a great help to understand some of the concepts behind IPFS, but as they are a work in progress some parts are incomplete or non-existing
• There is so much information and discussions spread around, some of it is in the GitHub issues, sometimes it's in the comments of PRs, it's really hard to keep track
• Entering the IPFS project without having a deep knowledge about P2P, Blockchain, Networking and Cryptography is pretty daunting
  • There is a huge amount of concepts flying around, and no centralized place where you can learn about them
  • It would be great to have something like a FAQ explaining some concepts or linking to solid references such as DHTs, Merkle DAGs or even Blockchains and Bittorrent
  • Of course you can search the web and read about it, but being that IPFS relies heavily on these concepts, they could have a place or spec explaining them and how IPFS uses them, as you can easily read an article that has pure wrong information
  • Reading the source code is a great way to learn how some things work, and makes IPFS a bit less daunting
• The issue #58 of the ipfs-docs repo seems to want to address many of the problems described above
• I find the description of most of the issues a bit blurry as I'm new to the project, it's not always clear to me what modules will need to be affected to solve some issues
  • It would be a great help if we could somehow tag the packages that need changes in some issues as this would point new contributors in the right path
• There are many cross references between issues and PRs, in a way this is pretty great to help to keep track of changes and similar problems, but sometimes I find myself digging deep inside issues and losing track of the original one
• Having some kind of a guide about how js-ipfs glues some of the packages together would be awesome, it will be an extensive task but I think it would be worth it
• We could start to adopt async/await and promises, as the JavaScript ecosystem is evolving in that direction
  • This is a never ending discussion, but in my opinion it makes the code more readable and new developers will probably have a better understanding of the source code

Take this with a grain of salt :)

[victorb]

Entering the IPFS project without having a deep knowledge about P2P, Blockchain, Networking and Cryptography is pretty daunting

As someone with exactly the same lack of deep knowledge, I started https://github.com/victorbjelkholm/dweb-wiki for trying to write down what I learned, but I quickly fell out of the habit of updating it. Making dweb-wiki into a ipfs-shipyard project and actually start filling it out would be great, and even greater if the wiki software itself was decentralized, but probably overkill for now.

Thanks for the overall feedback though, as David said, it's very helpful :+1:

[daviddias]

Thanks you so much for also posting this feedback here, @fsdiogo :) I'm leaving a few comments/follow up questions.

I've watched a bunch of talks by Juan about IPFS and they were a great intro to IPFS...

Do you know how many you watched and specifically which? Which parts were more useful? Do you happen to have notes from what you learn from which? We could potentially create a new talk just to focus on the details.

...I also understand that due to the complexity of the project, it may not be possible to do that!...

No, I think you are right. In the beginning, IPFS was a big mountain, but now we are finally sharding that into smaller ones with the IPLD, libp2p and multiformats project.

Did the blog posts helped?

We could start to adopt async/await and promises, as the JavaScript ecosystem is evolving in that direction ...

Soon™ :) I’ll open that to consideration once Node.js 6 goes to Maintenance. We kind of follow the Node.js release cycle given as it has a very good success when it comes to upgrade its users and gives us a good baseline.

Actually, that is happening soon. Would you like to take lead and open a issue similar to the ones with exploration label — https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+label%3Aexploration to propose just that?

I’m also looking forward to https://nodejs.org/api/esm.html :)

[Mr0grog]

Thanks so much for taking the time to write this up, @fsdiogo! I know you already mentioned ipfs/docs#58, but if you have any specific feedback on it, please comment there :)

Likewise, if you think some concepts are missing from the list in ipfs/docs#56 or if you have some you think should be high priority, please comment there, too.

@VictorBjelkholm thanks for posting that dweb-wiki link! I’ll mine that for good bits.

[fsdiogo]

@VictorBjelkholm I agree, it would be pretty neat to have a wiki where we could start gathering some knowledge 👍

@diasdavid No problem!

Do you know how many you watched and specifically which?

I watched these and some bits & pieces of others I can't remember.

• IPFS Alpha Demo
• Stanford Seminar - IPFS and the Permanent Web
• IPFS Hands on Introduction
• Juan Benet: Enter the Merkle Forest

Which parts were more useful?

The motivation behind IPFS and the problems it can solve were pretty useful, as were the parallelism of some concepts and technologies that uses them (like how Git uses Merkle Trees and how IPFS wants to adapt that). I think that is a great way to explain some concepts with pretty well-known examples.

Do you happen to have notes from what you learn from which? We could potentially create a new talk just to focus on the details.

I didn't take notes, I only took some screenshots of slides that showed the IPFS layers and then some... I have some notes that I gathered from the IPFS repos, Wikipedia, etc, but not much. Yeah, , I think that would be helpful!

No, I think you are right. In the beginning, IPFS was a big mountain, but now we are finally sharding that into smaller ones with the IPLD, libp2p and multiformats project.

Did the blog posts helped?

I felt like they weren't very foundable, some of them should be linked in the specs or something like that. I stumbled upon one post about pubsub that was helpful, but I don't remember where I saw the link, probably by searching for the topic on google.

Soon™ :) I’ll open that to consideration once Node.js 6 goes to Maintenance. We kind of follow the Node.js release cycle given as it has a very good success when it comes to upgrade its users and gives us a good baseline.

Alright, but the sooner the better 😄

Actually, that is happening soon. Would you like to take lead and open a issue similar to the ones with exploration label — https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+label%3Aexploration to propose just that?

Sure 👍

I’m also looking forward to https://nodejs.org/api/esm.html :)

Oh yeah! The future is bright 😄

@Mr0grog Will do! And good job on those issues, I think you're right on the money 👍

[0x-r4bbit]

Hi everyone,

I'm starting to get my feet wet with IPFS as well and try to take it one protocol at a time. I started getting a better understanding of IPLD and took a closer look at the Multihash protocol as part of it.

There's a a lot of different resources and reasoning spread in different places, so I've written an article that should provide all the information in one place and hopefully makes it easy to understand what's going on down there.

Maybe it make sense to introduce a page with resources or something (if not feel free to ignore it): https://pascalprecht.github.io/posts/future-proofed-hashes-with-multihash/

[fsdiogo]

Awesome post @PascalPrecht 👌

This is the kind of thing that we need, for everything 😄

We should gather resources like this somewhere. Maybe in the awesome-ipfs?

[0x-r4bbit]

@fsdiogo thanks!

I'm happy to send a PR to awesome-ipfs, I do think though, apart from that (and from this article), there should be a dedicated resources section/document in the official documentation.

[Mr0grog]

Ooh, nice writeup, @PascalPrecht!

I'm happy to send a PR to awesome-ipfs, I do think though, apart from that (and from this article), there should be a dedicated resources section/document in the official documentation.

For now, I’ve tried to make sure awesome-ipfs is linked from the new docs site — I worry about duplicating the effort of linking to external resources between the new docs site and awesome-ipfs leading to the same disconnect, out-of-sync-ness, and confusion we currently have :\

One way to address this might be to have the docs site generate a page (or several) based on what’s in awesome-ipfs, just like it generates some Go API docs from the Go source. Or, after the new docs site actually gets shipped, we could move all of awesome-ipfs’s content into it and deprecate awesome-ipfs. Either way, we can only do so many things at once, so awesome-ipfs is definitely the best place for now.

ALSO! Would you be interested in translating your post into a “concept” doc for the new site about hashes and/or multihash? I’d be happy to review a PR that adds a new page (or pages) to the content/guides/concepts/ folder :)

[0x-r4bbit]

Ooh, nice writeup, @PascalPrecht!

@Mr0grog ha, thanks. I hope it'll be useful to some ppl out there.

For now, I’ve tried to make sure awesome-ipfs is linked from the new docs site — I worry about duplicating the effort of linking to external resources between the new docs site and awesome-ipfs leading to the same disconnect, out-of-sync-ness, and confusion we currently have :\

Yes, this makes perfect sense.

I personally would vote for moving relevant links from awesome-ipfs to the new docs as this is going to be the main entry point for most of the people (unless we make people go to awesome-ipfs all the time). awesome-ipfs wouldn't even have to be deprecated for that but just keep living along. If ppl feel like adding stuff to it, there'd be free to do so.

Either way, we can only do so many things at once, so awesome-ipfs is definitely the best place for now.

Yep! Always one step at a time. My comment was really more about the possible future where a docs site exist where stuff like this could be linked as resources.

ALSO! Would you be interested in translating your post into a “concept” doc for the new site about hashes and/or multihash? I’d be happy to review a PR that adds a new page (or pages) to the content/guides/concepts/ folder :)

Let me have a look at that.

[0x-r4bbit]

@Mr0grog first bits landing here https://github.com/ipfs/docs/pull/81