-
Notifications
You must be signed in to change notification settings - Fork 62
Write new “Introduction to IPFS” guide #60
Comments
I can take a stab at the first task this week. |
Great! This is the general outline I had started to think about (rougher near the end), but would love to hear your version:
|
It seems like this would be a great backbone for something I just pitched to @flyingzumwalt
https://gist.github.com/nothingismagick/d0980c2287a60023067e8a9ba9add8ce |
Perhaps instead of writing docs, more time should be spent on leveraging specs for documentation generation. The more I think about it, with this kind of complex system, hand-written documentation is doomed to be out of date as soon as it is written - specs and the respective test-driven development, however - must be up to date or else the product can't even be shipped... Then a human can come and write some "semantic sugar" to smoothen everything - you know, somebody that describes the basic principles, while letting the code describe itself. |
Neat! I think I agree with @flyingzumwalt that it would be good to see how this winds up working in practice for your own app and potentially use that as a basis for discussing how we might do it for IPFS. |
Here's an outline version with a pivot towards use-cases and examples for the two primary audiences: end-users and developers. It focuses on IPFS while leaving Libp2p as a separate exercise. Although given the topics on discuss, it might make sense to just fold libp2p concepts (e.g., pubsub, crdts) in here. My apologies for concepts that I'm misrepresenting as I'm still learning and have a bunch of newbie questions. Please call these errors out or highlight things that don't make sense. Thanks!
(list needs more coverage and improved categorization) |
Oh, I like adding something like “how do I use” or “use cases” between the “what is it” and “how does it work” sections! I was thinking I would try to massage examples/use cases into the parts of section 1, but making an explicit section may be clearer and less work for both the author and reader :)
I think this might be too much—the intro guide should be working hard to be concise and relatively easy to get through. I feel like this level of depth is better suited to use-case guides like the “running a pinning service” one described in #62. I’m going to spend some time over the next week working on a draft of this. Thanks! |
An e2e use case is a lot of work and I agree with you maybe not the right spot in the intro guide, but having a really simple example of something useful you can do right now would be great. Like sending someone a big video that is just too large for any free service like WeTransfer... or sending a picture-postcard to someone, then realizing that you spelled their name wrong but it’s ok because they are still sleeping and you update the pin with a new version. Ok, we’ll that last one is a bit contrived, but my suggestion is to use easy to grasp examples from the real world and show how you can do the same - or even better with IPFS... |
Cool. Excited to see a first draft. Please let me know how I can help! Re: e2e use case... I second@nothingismagick comment of using an example of something useful that they could do immediately. Even if it's a link to another page, and not directly included in the Getting Started, I think it would be hugely helpful to get someone off the ground. |
Draft of the very first section (a high level overview — “what is IPFS?”) is up in #67 for anyone who wants to give feedback. |
I'm picking this up -- or what parts of it I can manage at the moment. Work underway in #170 . |
Closing this issue, since it's superseded by #170. |
We should write a new guide that largely replaces https://ipfs.io/docs/getting-started/ and the IPFS white paper. Rather than focusing on the CLI, it should focus on the concepts and workings of IPFS, using the CLI to demonstrate those ideas.
I’ve kept this separate from #8, where the discussion seems more focused around an introductory usage doc for each as described in the “later” section of #58. But if we should merge them together, let me know here!
First task here: a rough outline.
The text was updated successfully, but these errors were encountered: