Hi Mark,
Thanks a lot for the comments. Everyone including myself can learn more and be more efficient for spec text writing. Will share the updated version later.
Regards
Ross Jian Yu
于健
Huawei Technologies
发件人: Mark Rison <m.rison@xxxxxxxxxxx>
发送时间: 2024年12月6日
20:54
收件人: Yujian (Ross Yu) <ross.yujian@xxxxxxxxxx>; STDS-802-11-TGBN@xxxxxxxxxxxxxxxxx
主题: RE: Guide for TGbn specification drafting
Thanks for this, Ross.
A few other things worth mentioning, I think:
- Slide 6. There should be no normative verbs (shall/should/may) in Clause 9
- Slide 6. Do not use "may not", use "shall not"
- Slide 8. "only" is a fantastic generator of ambiguity because of lack of
clear precedence. The example given is:
“A STA shall only transmit an Ack when it receives a packet” should be “A STA shall transmit an Ack only when it receives
a packet” is right.
but does the latter mean:
A STA shall transmit an Ack only (not some other frame) when it receives a packet
or
A STA shall transmit an Ack only when it receives a packet (not at some other time)
?
I really would advise against use of "only"
- Slide 10. TGme (and specifically Brian) made a big effort to get rid of
use of "frame" to mean PPDU. "frame" must not be used to mean PPDU
In the attached I made some other suggestions, including the following:
- Make sure you refer to frames/fields/etc. by their actual name. Don't abbreviate or otherwise fiddle with the name. Remember frames/fields/etc. have exactly one name.
If a field gets renamed, check your text for any references to that field and update them
- Make sure you refer to MIB variables/tables that actually exist (i.e. have a definition in Subannex C.3)
- Make sure each word in frame/field/etc. names starts with an uppercase letter (but check the rules for hyphenated words)
- In Clause 9, do not give field/etc. sizes in text if already given in a figure
- In Clause 9, do not say fields contain little-endian/unsigned/etc. integers (since this is the default per 9.2.2)
- In Subclause 9.4.2 etc., follow the most common template for the structure of a new subclause
- Do not duplicate in Clause != 9 format/encoding information given in Clause 9
- Do not put behaviour in Clause 9
- Make sure you don't forget articles (the/a/an), but also make sure you don't include articles for uncountable nouns (or pluralise them!). If your native language doesn't
have articles, ask a colleague whose native language does to proof-read
More stuff that occurs to me:
- In Clauses 3.1/3.2 you need to expand the first use of any abbreviation
(including recursively) and you need to put the full abbreviation if any
in square brackets after the colon if it doesn't already appear before the colon
- There used to be a rule that hyphens shall not be used (even if
English grammar would demand them), but I this was rescinded in the
dying days of TGme, so hyphens should now be used correctly (but check
the rules on capitalisation of hyphenated terms)
- Don't say "the value of the xxx field" because per Subclause 1.3
you can just say "the xxx field is"
- "Clause" and "Subclause" followed by a number are uppercase
(but it's sufficient to say "see 12.13.14")
Thanks,
Mark
--
Mark RISON, Standards Architect, WLAN English/Esperanto/Français
Samsung Cambridge Solution Centre Tel: +44 1223 434600
1 Cambridge Square, Cambridge CB4 0AE Fax: +44 1223 434601
ROYAUME UNI WWW:
http://www.samsung.com/uk
From: Yujian (Ross Yu) <00001792b51ef4ea-dmarc-request@xxxxxxxxxxxxxxxxx>
Sent: Wednesday, 4 December 2024 07:03
To: STDS-802-11-TGBN@xxxxxxxxxxxxxxxxx
Subject: [STDS-802-11-TGBN] Guide for TGbn specification drafting
Hi all,
I have updated “A Guide for TGbn Specification Drafting” to r1:
https://mentor.ieee.org/802.11/dcn/24/11-24-1989-01-00bn-a-guide-for-tgbn-specification-drafting.ppt
This version reflected the suggested changes during my presentation.
regards
于健 Ross Jian Yu
Huawei Technologies
发件人: Yujian
(Ross Yu)
发送时间: 2024年11月26日
8:40
收件人: 'STDS-802-11-TGBN@xxxxxxxxxxxxxxxxx' <STDS-802-11-TGBN@xxxxxxxxxxxxxxxxx>
主题: TGbn D0.1 spec skeleton/tentative table of contents
Hi all,
I have prepared and uploaded a spec skeleton /tentative table of contents for TGbn D0.1.
https://mentor.ieee.org/802.11/dcn/24/11-24-1993-00-00bn-tgbn-d0-1-spec-skeleton.docx
Your comments are welcome.
Meanwhile, I am preparing A Guide for TGbn Specification Drafting, and will upload soon.
regards
于健 Ross Jian Yu
Huawei Technologies
To unsubscribe from the STDS-802-11-TGBN list, click the following link:
https://listserv.ieee.org/cgi-bin/wa?SUBED1=STDS-802-11-TGBN&A=1
|
|
To unsubscribe from the STDS-802-11-TGBN list, click the following link: https://listserv.ieee.org/cgi-bin/wa?SUBED1=STDS-802-11-TGBN&A=1