feat: improvements on docs #24

danisharora099 · 2022-12-05T04:24:14Z

Addresses #15

Followup:

Refactor Protocols Overview by Example to be more readable for the end user

vercel · 2022-12-05T04:24:19Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
waku-guide	✅ Ready (Inspect)	Visit Preview	Dec 15, 2022 at 3:41AM (UTC)

fryorcraken · 2022-12-06T05:00:34Z

Can we move away from the 1.md etc filenames? Just make reviewing hard as the whole content of each file is changed and not sure if it's on purpose or just some section were re-ordered/shifted.

I wonder if it's possible to set the page order via header metadata like in Hugo?

docs/Concepts/1.md

docs/Concepts/2.md

docs/Concepts/3.md

docs/Concepts/7.md

docs/Concepts/8.md

static/sequnce-charts/protocols-overview/overview.msc

Co-authored-by: fryorcraken.eth <[email protected]>

danisharora099 · 2022-12-09T05:53:08Z

Can we move away from the 1.md etc filenames? Just make reviewing hard as the whole content of each file is changed and not sure if it's on purpose or just some section were re-ordered/shifted.

I wonder if it's possible to set the page order via header metadata like in Hugo?

Great point.
Addressed here: https://github.com/waku-org/waku.guide/pull/27/files

fryorcraken · 2022-12-13T03:22:55Z

Smaller PRs in the future please. This is too cumbersome to review.

docs/Concepts/1.md

fryorcraken · 2022-12-09T06:45:38Z

docs/Concepts/3.md

@@ -1,46 +1,49 @@
 ---
-title: Content Topic and How to Choose One
+title: Protocols Overview by Example


I'd rather delete this page and re-write from scratch in a different PR.

On principle, the schema is a good idea but it's not readable in the current state. The mental load to read the diagram is too high:

TMI: we can exclude pubsub topic and encryption from it

Terminology is a bit too specialized, ie "history query" for a store query

too many participants: may make sense to split the diagram to illustrate different points.

made a note!
can we merge this for now, and I can followup with the refactoring in another PR.

this would also allow the existing #27 to not encounter any merge conflicts.

docs/Concepts/4.md

fryorcraken · 2022-12-13T03:19:04Z

docs/Concepts/6.md


-Waku includes a number of protocol covering the following domains like privacy preservation, censorship resistance, portability/runs anywhere.
+- `/supercrypto/1/notification/proto`
+- `/supercrypto/1/private-message/proto`



@kaiserd I believe we are looking in strategy to improve anonymity around content topic usage, similarly to what Status protocol does with their content topic (4 bytes of the hash of a key).

Am I correct? Should we mention that recommendation that are more privacy minded are in the works? Do we ahve an issue that tracks the work?

This is part of the pubsub Topic milestone, part of vacp2p/research#154
We do not have anything concrete at this point though. I am not sure, it will involve having specific content topic names. Most likely, deciding on content topics (including naming) will be up to applications. Waku will make sure the mapping of content topics to pubsub Topics preserves anonymity properties.

docs/Concepts/6.md

docs/Concepts/8.md

danisharora099 · 2022-12-14T08:52:28Z

Smaller PRs in the future please. This is too cumbersome to review.

Agreed! Documentations have been hard to track, with very unreadable diff.
Should get significantly improved with #27 - thanks for your patience! @fryorcraken

docs/Concepts/4.md

fryorcraken · 2022-12-15T02:45:16Z

docs/Concepts/6.md

+The recommended format for content topics is as follows:

-Waku offers incentivization mechanisms to run nodes, whereas libp2p does not.
+`/{dapp-name}/{version}/{content-topic-name}/{encoding}`

-Additionally, a user or a developer does not have to deploy own infra as a prerequisite to use Waku, it is a service network.
-However, it is encouraged to [run your own node](https://github.com/status-im/nwaku/tree/master/docs/operators) to support and decentralize the network.
+- `dapp-name`: The name of your dApp, it must be unique to avoid conflict with other dApps.
+- `version`: We usually start at `1`, useful when introducing breaking changes in your messages.
+- `content-topic-name`: The actual content topic name to use for filtering.
+  If your dApp uses Waku for several features,
+  you should use a content topic per feature.
+- `encoding`: The encoding format of the message, [Protobuf](https://developers.google.com/protocol-buffers) is most often used: `proto`.



@danisharora099 let's remove pubsub topics from the doc for now.

fryorcraken

Well done

* add: security features * add: protocols overview by example * add: different protocols * add: spell check on CI * rm: yarn.lock to avoid inconsistencies * Update docs/Concepts/1.md Co-authored-by: fryorcraken.eth <[email protected]> * Update docs/Concepts/2.md Co-authored-by: fryorcraken.eth <[email protected]> * Update docs/Concepts/2.md Co-authored-by: fryorcraken.eth <[email protected]> * Update docs/Concepts/7.md Co-authored-by: fryorcraken.eth <[email protected]> * Update docs/Concepts/7.md Co-authored-by: fryorcraken.eth <[email protected]> * convert mscgen sequence to mermaid * partially adress review comments * address: comments * fix: ci * chore: address minor typos/changes in docs * add: pros/cons for discv5 and peer-exchange * fix: minor typo * chore: address refactoring Co-authored-by: fryorcraken.eth <[email protected]>

* Use Logos plugins and theme. * Upgrade dependencies. * feat: improvements on docs (#24) * add: security features * add: protocols overview by example * add: different protocols * add: spell check on CI * rm: yarn.lock to avoid inconsistencies * Update docs/Concepts/1.md Co-authored-by: fryorcraken.eth <[email protected]> * Update docs/Concepts/2.md Co-authored-by: fryorcraken.eth <[email protected]> * Update docs/Concepts/2.md Co-authored-by: fryorcraken.eth <[email protected]> * Update docs/Concepts/7.md Co-authored-by: fryorcraken.eth <[email protected]> * Update docs/Concepts/7.md Co-authored-by: fryorcraken.eth <[email protected]> * convert mscgen sequence to mermaid * partially adress review comments * address: comments * fix: ci * chore: address minor typos/changes in docs * add: pros/cons for discv5 and peer-exchange * fix: minor typo * chore: address refactoring Co-authored-by: fryorcraken.eth <[email protected]> * chore: refactor ordering/naming of markdown files (#29) * chore: rename md files and use config ordering it is unfeasible to track the changes in files labelled as '1.md', '2.md', etc and way easier when the files are named after their contents. * fix: hint box render * fix: markdown links * finish merge * push yarn.lock Co-authored-by: Hossein Mehrabi <[email protected]> Co-authored-by: fryorcraken.eth <[email protected]>

danisharora099 added 2 commits December 5, 2022 09:45

add: security features

ee8294b

add: protocols overview by example

1c9aed7

vercel bot deployed to Preview December 5, 2022 04:30 View deployment

This was referenced Dec 5, 2022

refactor: security features #23

Closed

add: protocol overview by example #22

Closed

add: section on different types of protocols in waku #21

Closed

danisharora099 requested a review from fryorcraken December 5, 2022 05:34

add: different protocols

c891cc3

danisharora099 force-pushed the feat/improvements branch from ac17ef3 to c891cc3 Compare December 5, 2022 06:45

vercel bot deployed to Preview December 5, 2022 06:45 View deployment

vercel bot deployed to Preview December 5, 2022 06:54 View deployment

add: spell check on CI

753d4ed

danisharora099 force-pushed the feat/improvements branch from 5ec4692 to 753d4ed Compare December 5, 2022 06:56

vercel bot deployed to Preview December 5, 2022 06:57 View deployment

rm: yarn.lock to avoid inconsistencies

33d6303

vercel bot deployed to Preview December 5, 2022 06:59 View deployment

danisharora099 mentioned this pull request Dec 5, 2022

Improvements #15

Closed

7 tasks

fryorcraken reviewed Dec 7, 2022

View reviewed changes

danisharora099 and others added 2 commits December 8, 2022 16:20

Update docs/Concepts/1.md

4c29d8e

Co-authored-by: fryorcraken.eth <[email protected]>

Update docs/Concepts/2.md

5f016ba

Co-authored-by: fryorcraken.eth <[email protected]>

vercel bot deployed to Preview December 8, 2022 10:51 View deployment

Update docs/Concepts/2.md

f290346

Co-authored-by: fryorcraken.eth <[email protected]>

vercel bot deployed to Preview December 8, 2022 10:54 View deployment

Update docs/Concepts/7.md

c4598ce

Co-authored-by: fryorcraken.eth <[email protected]>

vercel bot deployed to Preview December 8, 2022 10:55 View deployment

Update docs/Concepts/7.md

3b3de90

Co-authored-by: fryorcraken.eth <[email protected]>

vercel bot deployed to Preview December 8, 2022 10:56 View deployment

convert mscgen sequence to mermaid

7e47a7b

vercel bot deployed to Preview December 8, 2022 12:10 View deployment

partially adress review comments

813036d

vercel bot deployed to Preview December 8, 2022 12:44 View deployment

address: comments

288a58d

vercel bot deployed to Preview December 9, 2022 05:08 View deployment

danisharora099 mentioned this pull request Dec 9, 2022

chore: refactor ordering/naming of markdown files #27

Closed

danisharora099 requested a review from fryorcraken December 9, 2022 05:53

fix: ci

6e2d54a

vercel bot deployed to Preview December 9, 2022 06:34 View deployment

jm-clius mentioned this pull request Dec 9, 2022

docs: improved filter specification vacp2p/rfc#562

Merged

fryorcraken reviewed Dec 13, 2022

View reviewed changes

chore: address minor typos/changes in docs

9a70870

vercel bot deployed to Preview December 14, 2022 08:14 View deployment

add: pros/cons for discv5 and peer-exchange

41c5651

vercel bot deployed to Preview December 14, 2022 08:51 View deployment

fix: minor typo

8cc6d41

vercel bot deployed to Preview December 14, 2022 08:51 View deployment

danisharora099 requested a review from fryorcraken December 14, 2022 08:54

fryorcraken reviewed Dec 15, 2022

View reviewed changes

chore: address refactoring

cbc894a

vercel bot deployed to Preview December 15, 2022 03:41 View deployment

danisharora099 requested a review from fryorcraken December 15, 2022 03:41

fryorcraken approved these changes Dec 19, 2022

View reviewed changes

danisharora099 merged commit 4413612 into staging Dec 19, 2022

danisharora099 deleted the feat/improvements branch December 19, 2022 11:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: improvements on docs #24

feat: improvements on docs #24

danisharora099 commented Dec 5, 2022 •

edited

Loading

vercel bot commented Dec 5, 2022 •

edited

Loading

fryorcraken commented Dec 6, 2022

danisharora099 commented Dec 9, 2022

fryorcraken commented Dec 13, 2022

fryorcraken Dec 9, 2022

danisharora099 Dec 14, 2022 •

edited

Loading

fryorcraken Dec 13, 2022

kaiserd Dec 13, 2022

danisharora099 commented Dec 14, 2022

fryorcraken Dec 15, 2022

fryorcraken left a comment

feat: improvements on docs #24

feat: improvements on docs #24

Conversation

danisharora099 commented Dec 5, 2022 • edited Loading

vercel bot commented Dec 5, 2022 • edited Loading

fryorcraken commented Dec 6, 2022

danisharora099 commented Dec 9, 2022

fryorcraken commented Dec 13, 2022

fryorcraken Dec 9, 2022

Choose a reason for hiding this comment

danisharora099 Dec 14, 2022 • edited Loading

Choose a reason for hiding this comment

fryorcraken Dec 13, 2022

Choose a reason for hiding this comment

kaiserd Dec 13, 2022

Choose a reason for hiding this comment

danisharora099 commented Dec 14, 2022

fryorcraken Dec 15, 2022

Choose a reason for hiding this comment

fryorcraken left a comment

Choose a reason for hiding this comment

danisharora099 commented Dec 5, 2022 •

edited

Loading

vercel bot commented Dec 5, 2022 •

edited

Loading

danisharora099 Dec 14, 2022 •

edited

Loading