search

ipfs / ipfs-docs

📚IPFS documentation platform
https://docs.ipfs.tech
299 stars 411 forks source link

Key terminology guide and which functionality is supported in which contexts #678

Closed BigLep closed 3 years ago

BigLep commented 3 years ago

Observed problem

When having conversations internal and external to PL about IPFS, we sometimes spend ~15 minutes getting everyone on the same page about terminology and what functionality is supported in which context.

Cause 1: Unfamiliarity with what is supported where

IPFS as a protocol brings together varying developer audiences (e.g., systems/go developers using go-ipfs, web/js developers using js-ipfs) talking about different contexts (go daemon, JS web browser, JS in NodeJS). We have observed that oftentimes these different parties don't know about important nuances about these different contexts in general or about the differences in the ipfs implementations.

For example, for a Go/system developer, they may not know:

  1. What you can do in a browser is different than what you can do with NodeJS
  2. Furthermore, what you can do in a browser depends on the context (main thread vs. WebWorker vs. ServiceWorker)

In addition, there is functionality in go-ipfs that just hasn't been implemented in js-ipfs.

Documenting in some way what functionality works in which context will help when making/evaluating proposals. I imagine there's a good way to do this visually, but even just capturing the facts in text form will help.

Cause 2: ambiguous language

Conversations are also hampered because of a lack of precision. Examples include:

  1. Using the overly generic word "node". It's easy for this to be confused with "NodeJS" or an "ipfs node".
  2. We defined our own terms for things in WebRTC for example that already have a publicly agreed-upon and accepted name. We spend time explaining the IPFS terminology when we could short-circuit the whole conversation by using the "official" WebRTC term.

Potential End Results

Putting this all together makes me think we should have a "having conversations about IPFS primer" that covers things like:

  1. Be aware that IPFS functionality varies across contexts (linking/citing information related to Cause #1 above)
  2. Avoid these unqualified/generic terms (e.g., "node")
  3. Links to the glossary with additional commonly confused terms.

This will help ensure everyone comes into the discussion with a base-level understanding.

Related

I'm filing this issue after hearing observations made by @lidel. He should come through and make any edits/changes/improvements.

welcome[bot] commented 3 years ago

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:

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

BigLep commented 3 years ago

@lidel : it would be good to get you take on what is missing in https://docs.ipfs.io/project/implementation-status/ that would have helped your discussions. I assume one is that "JS" isn't specific enough to the context where the JS is running (browser vs. NodeJS).

johnnymatthews commented 3 years ago

Thanks for the issue @BigLep; there are a few things to unpack and discuss here before making an actionable task-list.

Unfamiliarity with what is supported where

This is a fair point, especially when it comes to the difference between Go-IPFS and JS-IPFS. One assumption folks often make is that Go-IPFS and JS-IPFS have feature parity, but that is sadly not the case. This makes things tricky for things like reference docs where features exist in one version but not the other.

For example, for a Go/system developer, they may not know

A Go/system developer would likely use the Go-IPFS implementation, no? We would expect a web developer to know that Node.js apps contain features that browser-based apps don't, and the difference between web workers and service workers. If the reader doesn't know these things, documentation already exists on other websites.

I hope I'm not missing your point here. If I am, please correct me! It'd be really nice to have all the knowledge every reader needs in one handy place, but that just isn't feasible.

Using the overly generic word "node".

Can you link to other generic words we use? In defense of node: we try to use Node.js when referring to the javascript framework, and IPFS node == node.. I'm sorry if it looks like I'm nit-picking here. I want to understand what you mean by generic. More examples will help.

We defined our own terms for things in WebRTC, for example, that already have a publicly agreed-upon and accepted name.

Can you link to any examples of where we're using one term, but we could be using a WebRTC term? I'm not aware of WebRTC terms.

lidel commented 3 years ago

I think the main issue with https://docs.ipfs.io/project/implementation-status/ is that is.. way too detailed without any onramp/context :) (smaller issue is that it was not updated and tables are partially invalid) We need something that makes it obviously clear what the feature set diff is (transports, dht, etc).

Perhaps we could preface the page with an infographic or at least a table with high-level differences? I suspect we also may want to decrease the number of details as it will get out of date unless we are comitted to maintaining the data in tables.

We would expect a web developer to know that Node.js apps contain features that browser-based apps don't [..]

You would think that, but in my experience web developers have no need to think about "available transports" because its never in problem space during regular webdev. HTTP is water. Devs are fish. Can't expect them to think about rainbows in the sky :-)

I think there is a path towards improving this. What if we deduplicate content from https://github.com/ipfs/js-ipfs/blob/master/docs/BROWSERS.md and ensure its easy to find/discover on docs.ipfs.io? Right now the best docs/explainer for this are outside of docs.ipfs.io, which is unfortunate.

Using the overly generic word "node". [..] IPFS node == node. More examples will help.

That usually works, but sometimes even "IPFS node" is not precise enough. @Gozala created a nice summary of all "IPFS nodes" here and some more info here. Perhaps we could convert it into explainer that both removes ambiguity and describes the difference in feature set between js-ipfs and go-ipfs? Or at least add them to glossary. lmk how can I help.

Can you link to any examples of where we're using one term, but we could be using a WebRTC term?

I believe this is about things like STUN, ICE, TURN.
In libp2p we have STUN solution called AutoNAT. Our version of TURN are Circuit Relays, etc. Generic issues here is that we seem to lack docs that connect "generic names" with our internal solutions.

My idea is to add both "generic" and "ours" names to https://docs.ipfs.io/concepts/glossary/ and cross-link them. Would that make sense? (I can PR if ok)

BigLep commented 3 years ago

@lidel : thanks for filling in.

@johnnymatthews : I think responses to your questions have been provided. I feel like this issue hasn't come in cleanly packaged so it can be easily actioned on. If you'd like us to come back with a distilled list of specifics (e.g., update page X with the content from Y) or submit some starter PR's let us know. Thanks a lot - much appreciated.

johnnymatthews commented 3 years ago

[...] its never in problem space during regular webdev [...] - @lidel

That's a fair point. I guess that web-3 devs are gonna have to re-learn some stuff about the internet.

What if we deduplicate content [...] - @lidel

This is already on my radar in the Single-source documentation project

[...] created a nice summary of all [...] - @lidel

This is super useful. I hadn't considered all those uses of node. We could definitely put those terms into the Glossary at the very least. I've created #683 to tackle this. If anyone gets a chance to close that issue, I'd really appreciate it.

[...] STUN, ICE, TURN - @lidel

It looks like network traversal is becoming a bigger and bigger thing within the web-3 space. It's not something I have a huge amount knowledge on, but I get the impression that I'm gonna have to start reading up on it :smile:. Using generic names seems like a fairly nuanced issue. Would either of you two (@lidel, @BigLep) be able to create a stand-alone issue explaining why and where we should use terms like STUN, ICE, TURN? You don't have to assign yourself to the issue, but if you could give me a jumping off point that'd be appreicated.

[...] I think responses to your questions have been provided [...] _ @BigLep

Yeah I agree! You've both helped me understand what needs to be done here. With the creation of the two new issues (#683 and the one about IETF standards), we can probably close this issue. Unless either have you have more to add?

Gozala commented 3 years ago

Thanks for starting this discussion. It is not only the issue with go / js devs seeing what works where, but I'd argue that even PL devs across language boundaries don't always have an accurate picture of what works where. I think it would be amazing if we had a place that gives high level overview and a way to zoom in to understand the details.

E.g. we have IPFS pubsub implemented across all supported environments, but as it turns out they do not interop for various reasons. That is to say things are quite a bit more complex than boolean 💚/💔.

I think if we had a good visibility into what current state of implementations and interop is we could make more informed decisions on what to prioritize to get the highest value for the effort. I'd happily support any efforts to do so to my best abilities.

In my project proposals I've intentionally tried to move from js/go to nodejs/go/web naming because platform limitations in web are wildly different than in node and bundling them together just muddies the waters both internally and externally. (I should also take responsibility for introducing ambiguity when referring to nodejs as node)

lidel commented 3 years ago

@johnnymatthews sgtm, we can close this one and continue in https://github.com/ipfs/ipfs-docs/issues/685 and #683, but I feel you may need to open additional one for cleaning up https://docs.ipfs.io/project/implementation-status, namely:

johnnymatthews commented 3 years ago

Nice. I've just made #697. Closing this one.