Versioned and centralised live documentation for examples

As shared by @raul in the Kyokan report (original thread can be seen here), some of the findings for adopting libp2p reported by various developers were “API Inconsistencies” and “Lack of Documentation” (see “ When Implemented And Understood libp2p Has Few Concrete Issues” finding). To showcase the former, I went through the “Getting Started” demo of version 0.27.x and was faced with the following error:

TypeError: Class constructor Mplex cannot be invoked without 'new'
    at Object.<anonymous> (/Users/hopr/Projects/libp2p/demo-js-libp2p/index.js:6:1)

It took me sometime to realise the documentation was a bit outdated. After a few changes and using other examples, I managed to put the libp2p-in-the-browser example online (see https://glitch.com/~libp2p-browser-demo), originally put together by @jacobheun.

Now, for the HackFS hackathon, it seems that the most up-to-date (i.e. 0.28.x documentation) lives in the js-libp2p-examples, with a very good walkthrough and introduction by Jacob. It seems that there isn’t a centralised place where all the documentation for libp2p with dynamic versions exists, which seems to match the notes from the Kyokan report.

Might I suggest we pool some efforts to put together such documentation? On a first glance this would meant something along these lines:

  • Look up for all references from a given implementation (e.g. js-libp2p) and point them to a single directory/repository (e.g. libp2p/js-libp2p-examples).
  • Remove all existent and/or outdated references for specific versions that might no longer be supported and focus on a specific baseline (e.g. 0.28.x). I’m aware libp2p is yet to be stable and the API is expected to change, but would be good to have a base version we can point entry level engineers to.
  • Setup a documentation engine able to generate version specific APIs and render those under a libp2p approved domain. The API is already in GitHub so it would be a matter of render those in something versionable (e.g. ReadTheDocs)
  • Review existing examples, ensure they work, freeze packages, and deploy live URLs users can use to see them working.

As a final note, as part of the KERNEL program, we are looking to actually build this documentation, based on the work already done by @shresthagrawal who put together this tutorial, code source available here. Let us know what would be the best way to collaborate together and/or whether libp2p and/or associated entities (e.g. Filecoin) have any particular plans in this direction. We would love to work together!

There has been some discussion around creating something like this, and supporting version tagging to allow users to filter for their specific version. https://github.com/libp2p/js-libp2p/issues/512 is one of the issues that spawned some of the discussions around this. We had somewhat netted out on creating a new repo to house a lot of this that @vasco-santos was looking into. This would also act as a way for community members to submit their own examples/projects.

In addition we need to ensure docs.libp2p.io stays up to date and gets some more love. The IPFS docs site, https://docs.ipfs.io/, has had an overhaul recently. I think we could pull from the lessons learned there to improve the libp2p docs.

1 Like

Sounds good! How we can help to stream line this documentation and/or repository? I know keeping documentation up to date is a bit tricky so I understand @raul’s comments on trying to get a CI pipeline able to test each of the dependencies.

We are current running a small study group at KERNEL, and the question we stumble upon the most are on when to use x transport module with which y peer discovery module. Might I also suggest some cookbooks that we can point beginners? I think the existing examples are already pretty good, and https://docs.ipfs.io is really complete. I guess the challenge here is having a way to provide a version to these docs. Maybe something we can change in the Hugo Template to make it look like this?

Another way would be to have a matrix of the examples and which ones had been implemented already under which version.

Last but not least, it would be great to have a list of existing bootstrap servers users can use with some status to be able to quickly test them instead of asking them to run their own ipfs node. By now seeing all the docs its clear to me there are many nodes sponsored by both FL and PL but it’s not easy for outsiders to rely on them, even if its just for demos and/or conferences. Might I suggest having a dashboard where outsiders can get a chance to take a look at nodes available?

Thanks!