[Tinyos Core WG] TEP 1 feedback

[David Gay]

There was no community feedback on TEP 1 (after several reminders), so
I did a reasonably careful read through. Here's my comments (I guess
we can post them to the wiki when it pops back up):

- Section 2: this should clarify that the keywords must be in
upper-case to count, and that uses of the keywords in lower-case
should be avoided if likely to cause confusion
  Possibly also add that non-keywords in upper-case SHOULD be avoided?

- Section 3, 2nd paragraph. "docutils template" is mentioned before
citing the reStructuredText stuff. Confusing to people who've never
heard of it. Suggestion: restructure sentence a bit.

- Section 3.1:
  Are the fields listed the only fields allowed?

  The TEP number sentence ending in "how a number is assigned to it"
reads awkwardly

  4th paragraph: This document is Best Current Practice. -> This
document's type is Best Current Practice.

  Description of Final status: Possibly replace "The values of its
header fields MUST NOT change. The header of a Final TEP MAY have an
"Obsoleted By" field added."
  by "The only change allowed in a Final TEP is the addition of an
"Obsoleted-by" field".
  (I found the current version slightly confusing)

- Section 3.2:
  A number of Final TEPs have appendices after the author information.
No Final TEP has appendices before the author information. Author
sections are numbered like regular sections, and appendices use
letters. Suggestion: change the last paragraph ("Author's Addresses"
comes last) of 3.2 to allow this. Possibly discuss other rules for
appendices?

And on a minor note, TEP 101 (which is Final) doesn't have an Author's
Addresses section. Oops.

David