[Tinyos Core WG] TEP 1 feedback

[David Gay]

On 5/29/07, Philip Levis <pal at cs.stanford.edu> wrote:
> 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.

I think "A TEP MAY have appendices after its Author section" should be
"A TEP MAY have appendices after its numbered sections" (appendices
come after citations, if any).

Also maybe rephrase "The last numbered section of a TEP (but before
citations, if there are any), entitled "Author's Address" or "Author's
Addresses" MUST contain detailed author contact information."  (it
says "it's the last one, but there may be another last one after it"
;-)).

David