Skip to content

Latest commit

 

History

History
76 lines (57 loc) · 5.62 KB

30-ipfs-education-and-documentation.md

File metadata and controls

76 lines (57 loc) · 5.62 KB
Raw

IPFS Docs

IPFS is kicking off a documentation revamp in Q3, with a team dedicated specifically to making it easier to contribute IPFS docs and maintain them. In this session, we will explore the state of our current documentation, and where the most valuable improvements could be made.

Goal

By the end of this session, we hope to pool our knowledge about the current state of IPFS documentation; the best descriptions and/or analogies of the DWeb and IPFS we've seen in the wild; favorite/least-favorite documentation approaches elsewhere; and priorities to tackle first. If there's time, we may hack on docs improvements together! #justdoit

Team

Presentation

🎤 Slides

Notes

Biggest problem

  • The code/docs reflect the organization of the company -- distributed
  • Docs need to be findable all in one place

We should set the stage first

  • Introduction guide (primer to dweb, IPFS) -- super useful at the start.
  • Story that links for more detail -- high level explanation, and then link or expand for more info. Storyline that pulls through everything.
  • Do a better job of explaining the d.web first, before getting into ipfs.
  • Oli’s presentation (Core Course D) -- if everyone could get that presentation when they start would be amazing.

Videos

  • Long form videos
  • Juan’s early talks where he would show the command line -- I’m huge on videos -- that type of thinking through the process. The developers going into the code -- even live coding -- or at least going through and saying this does this, and this does this -- esp with open source contributions, it’s really helpful to have this.

Metaphors and descriptions

  • Docs that come back to the same story throughout -- always about the bunny, for example. Or, PetShop by Truffle -- by the end you’ve got a fully working app
  • Putting concepts into context of applications
  • Metaphor of a library is good (looking for something via building --> stack --> shelf vs catalog/content)
  • I like when things are compared to the thing I’m used to.

More guides/explanations with opinions on best practice

  • I could use this in the node, or use this in the browser, but which would you recommend?
  • Really good examples can really kick-start a community. For example, X micro-payment platform, all their customers came through one demo.
  • Experienced coders think they’ve done a great job, but as a less experienced coders, I need examples that look like my use case, or more than one example. I can’t generalize.

Specific issues/suggestions with docs

  • I had trouble installing because when I got to install, it dropped me at a page with all the implementations, and didn’t tell me
  • API list, improve that documentation
  • Re: experience of writing book: I needed a lot of basic information -- asked Dr Juan for some research papers. Learn it carefully. Then, use simplify those difficult questions to Chinese words. Have to choose sentences and use of words very carefully, also because we’re publishing with a state-run publisher, we needed to make sure it was written well. We finished writing 6 months ago. After that, IPFS has many updates. Books aren’t the best solution. ProtoSchool, we can read, run, and debug our latest knowledge. That’s a better way for educate.
  • Different products -- Proto.School v Docs/API reference
  • Being able to have a time where a developer gets on a call and ask questions (We might not be doing enough to advertise existing options for this)
  • I can see how for me it wouldn’t matter to see the behind the curtain, but for a contributor, would need to know that. Learning how to use versus learning how to contribute to the implementations.

Creative ideas

  • Docs plugin for VS code (I wonder if there’s a structure that if you update documentation it updates the plugin, or links)
  • Can we store the docs about IPFS on IPFS?? And create reusable documentation format or product that other companies could use. So, we can improve our documentation and provide a documentation service as well. One product that can make more products.
  • China needs more professional ipfs education in Mandarin
  • The autogenerated documentation -- it’s better to have a way to contribute, let people help each other together. Otherwise, to fix it, you have to go to the code -- I don’t know where to go to find the code to find the autogenerated docs. Alternative example: single-page app where all content is a json file, and there’s one file per piece of content, which makes it easy to find. Single-page app automatically updates data when the API updates.

Describe motivations

  • Social justice issues, democratizing access to info and power,
  • Understanding how businesses make money is interesting and helps people understand the ecosystem. For example, 3box and textile short term cloud hosting, later giving different storage to people’s data and buildng in cryptoeconomic incentives.
  • We should help people understand if there are any business incentives, not just warm fuzzy incentives

Documentation people like

  • Ethereum Pet Shop
  • Vue.js
  • Textile’s articles and long-form videos
  • Consul.io
  • ipfs.docs.apiary (the style is good, with the side-by-side, because I need to debug and I can do that right there)

In-code docs/error/CLI

  • It has the behavior I would expect, very clean.