feat: soc and feeds documentation #37
Conversation
agazso
requested review from
AuHau,
Cafe137,
nugaon,
significance and
vojtechsimetka
vojtechsimetka
left a comment
vojtechsimetka
left a comment
There was a problem hiding this comment.
Thank you @agazso , I provided some grammar suggestions (please question any one of them) but there are one incomplete sentence which should be merged. Otherwise I am approving as it can be merged pretty much as is.
My only feedback (and it is also for me) would be to focus more on explaining why this functionality exists before diving into how to use it. But this is definitely something we can iterate on.
|
|
||
| Publishers are the single owners of feed chunks and are the only ones able to post updates to their feed. Posting an update requires (1) constructing the identifier from the topic and the correct index and (2) signing it concatenated together with the hash of the arbitrary content of the update. | ||
|
|
||
| Conversely, users can consume a feed by retrieving the chunk by its address. Retrieving an update requires the consumer to construct the address from the owner’s public key and the identifier. To calculate the identifier they need the topic and the appropriate index. For this they need to know the indexing scheme. |
There was a problem hiding this comment.
Could we try and break this down a bit? I am myself not sure I fully understand it, it just sounds like "you need this, but to get it you need this and this and for that you need also this and this".
There was a problem hiding this comment.
TBH I copied this verbatim from the Book of Swarm :)
As such I get it that the language is somewhat academic, so suggestions to improve are welcome.
There was a problem hiding this comment.
@significance ^^ maybe you could take a look at this?
There was a problem hiding this comment.
yeah i think it makes sense, but indeed academic and a maybe bit highbrow maybe for the docs.
if i were to suggest anything, maybe just that there is a tl;dr basic explanation at the start which simply states feeds are a key-value store / pub-sub system, then allow people to have a deeper dive if that's something they would be interested in.
in general i have tried to take the approach of keeping the docs as a simplistic user manual and leaving the deep theory for The Book. some has crept in from various PR's but that was the initial plan 😀
Co-authored-by: Vojtech Simetka <vojtech@simetka.cz>
No description provided.