[Discussion]Modularize Libp2p Docs

[jennijuju]

    Cheers @johnnymatthews @p-shahi

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)

[jennijuju]

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"?

[p-shahi]

@jennijuju
I think it makes sense to raise your questions in the same PR, I fear posting them in this issue might cause fragmentation. It might make sense to create an Epic later to track the different implementation efforts but I don't understand moving the discussion out of the PR just yet.

Also, we need to have the docs restructure proposal presented to the libp2p team as I mentioned here: #186 (comment)

My preference is a sync meeting where @DannyS03 presents the proposal and we can have a Q&A but I think for now we're waiting on a Loom video that the libp2p team can review async.

I'd also like to have the libp2p team review the docs roadmap since it's directly related to these efforts: https://hackmd.io/@fHBn7vDHS-aFUwXsOkXqGQ/HknZYaaGo#specslibp2pio
But I'm not sure if it's ready to share with the wider team yet

[jennijuju]

@jennijuju I think it makes sense to raise your questions in the same PR, I fear posting them in this issue might cause fragmentation. It might make sense to create an Epic later to track the different implementation efforts but I don't understand moving the discussion out of the PR just yet.

I moved it out cuz I agree with Marteen's comment given the scope of this is bigger than the PR. I'd like to minimize WIP PRs, so it either

• we are saying the "modularization" will happen in [META] General structure, flow, & content enhancements #186 then we should convert that pr to be in draft
• or we land that PR first, and continue further discussion on how we want to re-archietcture libp2p docs site in a new discussion, i.e: here

Also, we need to have the docs restructure proposal presented to the libp2p team as I mentioned here: #186 (comment)

Agree 💯 . note this issue was created with "discussion" in title and need/team-input as label to indicate this is an open discussion needs stakeholders input, not an executable issue yet.

I'd also like to have the libp2p team review the docs roadmap since it's directly related to these efforts: https://hackmd.io/@fHBn7vDHS-aFUwXsOkXqGQ/HknZYaaGo#specslibp2pio

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?

[p-shahi]

or we land that PR first, and continue further discussion on how we want to re-archietcture libp2p docs site in a new discussion, i.e: here

Gotcha, I agree with this. My preference is to land that PR as I generally agree with the approach to structuring the content.
Though in order to land the PR, we still need a quick walkthrough of the new content structure. It will help explain the vision. Again a short sync meeting with the team or a quick video will be good enough.

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

1. Sync meeting/short video for overview of content restructure in [META] General structure, flow, & content enhancements #186 and so it can get reviewed and merged ¹
2. written proposal (Notion preferably where people can easily comment) or sync meeting/video on docs website re-arch ²
3. 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

Footnotes

1. with the aim of answering questions like the one here "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." ↩

2. we need a team discussion to present this idea, address open questions in https://github.com/libp2p/docs/pull/186#issuecomment-1260337862 and in this issue, and get team approval. ↩

[jennijuju]

https://hackmd.io/@fHBn7vDHS-aFUwXsOkXqGQ/HknZYaaGo#Q4-2022

sg - just fyi the above doc is a very early draft of the proposed roadmap that hasn't been reviewed internally within the docs team. @DannyS03 potentially learnings for us here is: lets only share planning docs to the project teams when its ready for review & comment.

[salmad3]

thanks @jennijuju @p-shahi. I'd recommend that we utilize the "Discussions" forum available on the GitHub repo for this being an ongoing discussion

[salmad3]

Closing in favor of #210 (which captures the discussion) as we have backtracked somewhat on the initial approach and we don't have an executable issue here. Please reopen if otherwise.