search

libp2p / specs

Technical specifications for the libp2p networking stack
https://libp2p.io
1.58k stars 275 forks source link

Replace "main spec doc" with minimal index #175

Closed yusefnapora closed 5 years ago

yusefnapora commented 5 years ago

The main goal of this is to address #156 by moving the "main spec document" to an archive folder, replacing it with a minimal index into the specs that are currently living in subdirectories.

This is a fairly drastic move vs editing the main doc piecemeal to remove inaccuracies, but I think it's likely the cleanest way to provide visitors to the repo with a view into the currently active / supported specs. It also lets us keep the original document around as a reference, which I think is still useful, especially for getting your head around some of libp2p's design decisions and philosophy.

Over time we can add more contextual information to the README / index, such as splitting out sections for lifecycle stages and / or functionality (e.g. put the stream muxers together, etc).

closes #156

ghost commented 5 years ago

I'm a strong +1 on this. Right now when people come to the specs repo, what they see is a set of numbered chapters and a table of contents that we all agree is not the right content for people seeking specifications. The content is not bad (it helps to motivate the problem), it's just not what we want to put front-and-center for a specifications audience. This PR fixes that problem.

yusefnapora commented 5 years ago

I like the underscore, @jacobheun, that's a nice idea.

raulk commented 5 years ago

This is a great improvement @yusefnapora. Thanks for championing this!