Review and Feedback guidelines

How to comment on EEA documents

Please use the Contact Form on this website to provide comments on EEA Specifications including Review Drafts and Editor’s Drafts, and other documents provided through this website.

Please identify the specific version of specifications and documents that provide such information, e.g. “EthTrust Security Levels, Editor’s draft, 14 July 2032” or “EEA primer ‘Introduction to DAOs veersion 7′”, in the subject field, to ensdure the feedback is efficeintly delivered to the relevant Group or staff member.

Producing helpful feedback

Helpful feedback on specifications identifies

• the relevant part(s) of the specification. EEA specifications published as HTML generally have section markers (“§”) that are a link to the relevant section. Quoting that link is helpful, in addition to noting the section name and number.
• the problem with the current text, or the addition suggested. While it is helpful to identify action that would resolve the issue, it is important to explain the problem as the Working Group may decide a different resolution is more appropriate.

Feedback that suggests the use of a different definition, a change or improvement to grammar, a broken link, or the like, is best identified as “Editorial”. Please note that the editor(s) of any specification, at the direction of the relevant Working Group, take responsibility for decisions on writing style.

Feedback that identifies a problem with the content itself, such as noting an erroroneous statement, or a suggestion that a specification should include content it does not currently address, is substantive and will be considered by the Working Group as a whole. The Working Group might ask for further clarification to help it resolve the issue appropriately.

Good Feedback might look like:

Section B.6 (vii) “Interesting Fruit” of the 14 January Editor’s Draft of “Lunch ideas” <https://entethalliance.org/specs/drafts/2028-01-14-Lunch/#sec-interesting-fruit> contains Editorial and Substantive errors:

• Substantive: It fails to mention donuts, and it includes persimmons but they are not interesting
• Editorial: The common spelling is “donuts”, not “dough-nuts”. The spelling used will confuse the international audience of this specification.
• Editorial: The use of double- and triple-negatives and not writing in a way that does not use passive voice is not conducive to easy understanding. Please consider rephrasing this.

However feedback such as

The specification takes the wrong approach, because it doesn’t address the ideas of Shevchenko on Mishima’s later works properly.

Is difficult to process. While it suggests that something is missing, it fails to explain what that is (which ideas of Shevchenko?), nor give an understanding of how it could be fixed. Further, it doesn’t identify in any way which parts of the specification are problematic.