Next steps for libp2p documentation

[salmad3]

Modularize the libp2p documentation

Opening this discussion in favor of some of the ideas we have thrown around about ways we can improve the libp2p content in general, starting with #186. A video was created to provide more context for this PR, which is now outdated as we have modified the initial approach to be more practical and aim to improve the overall organization that gives the docs a better flow and allows us to start modularizing, instead of jumping right away to display something new, like a "book" with chapters. However, there are many ideas we have on the next steps for how we can revamp the libp2p content.

Somewhat a start for this discussion:

I’ve been considering a few things on how we can organize all the libp2p material. What seems like an interesting format to consider is eventually having something along the lines of the following:

• book.libp2p.io- more theoretical and conceptual - a public goods networking resource
• guides.libp2p.io - how to guides, examples and tutorials (doesn’t need chapters)
• implementations.libp2p.io - implementations page

The concepts are generally timeless (or can be considered to be), so I see the benefit in presenting them in a structured way, like a book. Part of this is also because we end up doing a good amount of information curation as different implementations document certain components and implementation specific content lives in the repos of those implementations. Likewise, as an implementer, you'd eventually be interested in the actual libp2p specs that go into details.

The changes here also try to show a proof of concept on how we can organize the content right now and offer a better flow, as I think the libp2p content benefits from a structured flow like this.

Originally posted by @DannyS03 in #186 (comment)

• Led into comments and concerns about the most recent PR that proposes structure changes.

Some thoughts:

• By @jennijuju, originally posted in [Discussion]Modularize Libp2p Docs #203:

a couple thoughts/questions

have multiple domains might diverge and confuse users.
what motivated book.? whats the difference between book. & spec.?
what would be the user journey for someone who say wants to learn about transport of libp2p? how many sites will they have to go through before they can understand the concepts and build something?
do we have any datapoints on why "guides and tutorials should be moved outside of the docs.libp2p.io"?

I am working on the docs team roadmap atm, and thats what lead me to this issue. As of now - im not sure if modularize libp2p docs should be our top priority as I dont see an obvious impact.
Im not saying we should not do this, however id like to understand

why we want to spend time to do a re-architecture of libp2p doc?
how did we come up with this proposed solution, what kind of user journey analysis have we done to land on this solution?
project wise with limited doc engineer resource - should we spend them on creating more content instead of rearchitecturing?

• By @p-shahi, originally posted in [Discussion]Modularize Libp2p Docs #203:

I think the next steps to move the ball forward should be

Sync meeting/short video for overview of content restructure in #186 and so it can get reviewed and merged 1
written proposal (Notion preferably where people can easily comment) or sync meeting/video on docs website re-arch 2
post the roadmap in #libp2p-implementers and #engres-ip-stewards and ask the libp2p team (and others) to review and suggest whether or not our high level priorities are aligned.
I am working on the docs team roadmap atm, and thats what lead me to this issue. As of now - im not sure if modularize libp2p docs should be our top priority as I dont see an obvious impact.

Yeah the current roadmap makes assumptions that we're heading in a certain direction without full stakeholder input/review.
The immediate top priorities for Q4 look reasonable but, whether or not the modularization should be a top priority in 2023 is still an open question.
So before committing it to the roadmap, we need to do 2

Yeah the current roadmap makes assumptions that we're heading in a certain direction without full stakeholder input/review.
The immediate top priorities for Q4 look reasonable but, whether or not the modularization should be a top priority in 2023 is still an open question.
So before committing it to the roadmap, we need to do 2

Footnotes:
with the aim of answering questions #186 (comment) "I'm not actually sure what the proposal of this PR is, and what a general proposal is. The fleek preview in the top comment doesn't work any more, so I also can't see what's going on." ↩

we need a team discussion to present this idea, address open questions in #186 (comment) and in this issue, and get team approval. ↩

---

Let's continue the discussion here, iterate on the roadmap(s), and draft a proposal that includes different approaches for next steps (in progress).

[marten-seemann]

I might be missing context here, but I'm really scared that we'll have too many layers when we split docs subdomain into book and guides is a good idea (not sure what implementations would be). Keep in mind that we also have a specs repository that's the authoritative source for everything libp2p related. It's already hard to keep the docs consistent and up to date with the specs, and introducing another layer of documentation would make that even harder.

[p-shahi]

There are a few proposals in the OP, some discussed in linked PRs/issues. Here are my updated thoughts

tl;dr at the bottom

Proposal 1. a new book.libp2p.io subdomain for the docs site

I vote against this.
Originally I was ok with it but now in my opinion we should keep it as docs.libp2p.io
A majority of technical doc sites use domains like docs.foo.org or foo.org/docs and I don't see a compelling reason to buck convention.
The Rust doc is a popular example of docs presented in a book format and it also uses doc.rust-lang.org/book(books for Cargo, rustc, etc. host their content in subdirectories under the doc.rust-lang.org domain /cargo, /rustc, etc.)

Proposal 2. structuring docs content in a book/chapter format

The concepts are generally timeless (or can be considered to be), so I see the benefit in presenting them in a structured way, like a book.

👍 I'm in favor of this. I liked the way it was presented in this preview.
Using the preview as a reference, my preference for organization is to:

• promote Basics and Core Components from chapters into parts (like Part I and Part II of books)
• promote all Core Component subchapters into chapters. Only number the chapters not their subchapters
• remove the Overview pages (text can go in the main chapter page)

Proposal 3. guides.libp2p.io as a new subdomain for "how to guides, examples and tutorials (doesn’t need chapters)"

I vote against this because I don't think we need a new subdomain to achieve what you want with modularity.
guides should remain a subdirectory under docs. I'm ok with the url changing from docs.libp2p.io/tutorials to docs.libp2p.io/guides however.

The problem is the Huge Learn theme, we need to move away from it.
This theme is not a good fit for housing content like guides/tutorials alongside technical docs because it prevents "Guides" from being distinct enough. Docs and guides should be presented distinctly because they are totally different types of content.

The main culprit is how rigid the left nav bar is.
It organizes the content sections but forces a continuity between them.

As a user, when I click on "Guides" in the left nav bar, I never leave the docs:

• I'm still clearly in the "Documentation portal" (evident from the breadcrumb)
• Hugo's left nav bar always lists the other sections (Intro, Core Comps, Reference, etc.)
• Guides section in the ever-present left nav bar and will make less sense if we structure the site like chapters (same applies to Reference, Community, Get Involved, etc. sections)

To achieve modularity between different types of content, we need a new theme.
Examples of themes that organize content well and their key features:

• https://docs.avax.network/
• https://developer.aleo.org/overview
  • horizontal nav bar up top with subdirectories segregated by tabs
  • dynamic left nav bar, displays content only for selected tab/subdirectory
  • dynamic right nav bar that's a Table of Contents for the page you're on
  • achieve all this with subdirectories and no new subdomains
  • (only Aleo) uses chapter organization for the main docs

I want the docs site sections to be be divided like that and the guide/tutorial content itself to be presented like

• https://docs.avax.network/subnets/create-a-local-subnet
• https://developer.aleo.org/leo/language/language

Another reason to ditch the Hugo Learn theme is how outdated it is. It looks like it's from 2005 🦖

Proposal 4. implementations.libp2p.io - implementations page

I don't think we need a new subdomain. Let's keep the subdir libp2p.io/implementations as is.
We can consider revamping its content and the main website but our efforts are better focused on the docs site first.

Following is from the Q1 2023 section of the hackmd page

Proposal 5. community.libp2p.io

Let's not create a new site, we already have docs.libp2p.io/community/ and libp2p.io/#community
I think docs.libp2p.io/community/ can be addressed by using a new theme and we can keep the other main site one as is.

Proposal 6. specs.libp2p.io

👍 👍 I think a rendered specs site is valuable. But likely as a subdirectory libp2p.io/specs or docs.libp2p.io/specs

There are existing solutions to deploy a site directly from the specs directory without needing to duplicate content or incurring maintenance overhead (aim should be zero overhead) for specs writers/maintainers.

My favorite examples are this spec site: https://internetcomputer.org/docs/current/references/ic-interface-spec/
rendered from this AsciiDoc: https://github.com/dfinity/interface-spec/blob/master/spec/index.adoc

and the Filecoin spec site https://spec.filecoin.io/

The rendered output is a nicer way to read the specifications. It matters more for casual users/new learners who are not writing/updating specs on a day to day basis.

The overall tone of the current specs are more around “this is what happens (or what needs to happen)” as opposed to “this is what happens and how it happens”.

This is intentional imo and I think it's the libp2p docs that should address “this is what happens and how it happens”.

The specifications can also use the UML diagrams available (and new ones that are created) as visuals for the specifications.

👍 yeah specs are the right place for sequence diagrams. As a spec reader they would be helpful additions.

Proposal 7. connectivity.libp2p.io

Work with stewards to add a phase of updates to the new connections site and improve overall UI/UX based on user feedback and analytics.

I agree but I don't think it should wait until '23 Q1. We've already deployed it and there are important changes to make.
Between Marten and me, we have collected a lot of feedback and need to start addressing them today.
Also need to migrate it from a subdomain to a subdirectory.

---

tl;dr

A key item we need to add to the docs roadmap is ditching Hugo Learn and using a more flexible, modern theme.
I think this addresses the heart of the docs re-arch/modularity proposal without needing to create new subdomains.

There's no reason to continue using the Hugo Learn theme when other docs site in the PL/Filecoin ecosystem just look way better: https://docs.filecoin.io/about-filecoin/what-is-filecoin/

IPFS docs theme isn't that modern but it still flows much better: https://docs.ipfs.tech/

The time & effort spent on this is well worth it for maintainers and end users.