Re: encouraging participation

[Alan DeKok <[e-mail]>]

On Jun 11, 2024, at 6:50 AM, Susan Hares <[e-mail]> wrote:
> You are correct that technical standards should use clear writing based on simple language. 

  I would also encourage standards to be written by (or at least reviewed by) implementors and other people who are expected to use the specification.

  A recent example of getting this wrong is RFC 7170.  It was about a decade after publication before anyone implemented it.  And then it was discovered that key things were missing, and it was therefore impossible to implement.  A years work later, and we have 7170bis with substantial changes.  The critical step in fixing the document was getting feedback from implementors, and people using it in real environments.

  There's also the issue that many specifications are written in a style to "remind" the reader about the subject.  i.e. they are written from the authors point of view, who is familiar with the area, and is therefore just documenting bits of the protocol.  The problem is that the reader doesn't have the same knowledge as the author, but is instead reading the document to gain that knowledge.

  The reader is then left mystified, as critical pieces of the specification are left unsaid, or are ambiguous.  The result is interoperability issues, and implementation confusion.

  In my experience, it's better to err on the side of more detail, rather than less.

  Alan DeKok.