[Tinyos Core WG] TEP 1 feedback

[Philip Levis]

On May 21, 2007, at 1:46 PM, David Gay wrote:

> 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.

I committed changes for all of the suggestions.

Phil