This forum post suggests a structure for WAKU RFCs that, imho, would help new developers filtering and digesting the information quicker.
What do you think?
I would suggest introducing categories for WAKU RFCs similar to RFC1796.
A first suggestion would be:
- documents containing normative specification of WAKU protocols
- these documents are the basis for implementations
- Waku2 implementations support a protocol if they adhere to the respective
- documents providing valuable but not normative information
- best current practice
- these documents describe suggestions for (practical) integration of Waku specifications
- e.g. a document describing which specifications are sensible for a mobile node to implement, and if available, which configuration options a mobile node might want to choose
We could also just introduce the first two categories and treat everything that is not
WAKU standard as
WAKU informational to keep it simple.
I would suggest dividing references into two categories as described in
Within an RFC, references to other documents fall into two general
categories: “normative” and “informative”. Broadly speaking, a
normative reference specifies a document that must be read to fully
understand or implement the subject matter in the new RFC, or whose
contents are effectively part of the new RFC, as its omission would
leave the new RFC incompletely specified. An informative reference
is not normative; rather, it provides only additional background
Imho, this would further help streamlining the process of getting to know a specification,
as it makes clear which references are crucial for a compatible implementation.
I would suggest the following structure for
WAKU standard RFCs.
This draft RR demonstrates the suggested structure.
(Documents of other categories would not be subject to this structure.)
Specifically, I suggest moving the security/privacy considerations to the end.
Even given security/privacy is the focus of Waku, imho a specification document is easier to comprehend
if it first covers a motivation/rationale followed by theory/semantics and wire-format/syntax.
After having understood these parts, the security implications are easier to comprehend.
Further, having separate theory/semantics and syntax/wire-format sections should help grasping the gist of the specification quicker, and also states more clearly which parts must be implemented in a specific way.
Generally, I think, having a common structure makes orienting oneself easier.
We could start using this scheme for new RFCs and update the
WAKU standard RFCs accordingly before publishing WAKU2 v1.0.