[sv-bc] FW: [sv-ac] some pointers for writing and reviewing proposals

 

-----Original Message-----
From: owner-sv-ac@eda.org [mailto:owner-sv-ac@eda.org] On Behalf Of John
Havlicek
Sent: Tuesday, September 25, 2007 8:35 AM
To: sv-ac@eda-stds.org
Cc: shalom.bresticker@intel.com
Subject: [sv-ac] some pointers for writing and reviewing proposals

Hi Folks:

In order to reduce the the number of proposals that get sent back from
Champions, we need to improve our quality assurance within SV-AC.

I asked Shalom Bresticker to help me assemble some pointer for writing
and reviewing proposals.

I think that by better applying such guidelines in the review and
balloting of proposals, we will increase our throughput at the
Champions' level.

J.H.


A checklist for writing and reviewing proposals:
------------------------------------------------

- Be consistent in the use of style and terminology both with the rest
  of the LRM and internally within the proposal.
  . Avoid unnecessary variations of words or turns of phrase that refer
    to technical concepts.

- Remember that is a standard, not a literary work. It does not have to
  be interesting.  It does have to be clear and precise.

- The text needs to be clear to someone who is not an expert in the
  subject material.

- Use cross-references freely.

- Are all terms either defined with the LRM or can reasonably be
  assumed to be known by the normal reader who is not an expert in the
  material?  Same for abbreviations, acronyms.

- Avoid overlong paragraphs. 5-6 printed lines is a good guideline. Up
  to 10 is tolerable.

- For all, but especially for those who are not native English
  speakers, have the text checked for spelling and grammar by someone
  who is good in English, unless you are good enough yourself.

- Show it to someone else within your company for review.

- Show it to someone from SV-BC or SV-EC (or SV-CC if relevant) for
  review. Often not practical, I know, especially if long.

- Avoid the trap of "The reader will be able to figure out for himself
  that the implication of this is ...". Better to be explicit. Space
  is not at a premium.

- Is the flow of subjects of the text logical and smooth? Does it jump
  back and forth?

- The editor should be able to figure out unambiguously and easily
  what he has to do. Don't push work on to the editor unless
  necessary. He has enough to do as it is.

- Try to avoid including substantive changes which are not directly
  connected to or beneficial to the main subject of the proposal,
  especially if they are liable to be controversial.  Consider filing
  a separate Mantis instead.

- Check for the correct use of shall/may/can/should as described in 1.5.

- Check for correct coloring instructions for the editor
  . existing text in black
  . deleted text red strikeout
  . new text in blue
  . syntax terminals in syntax boxes always bold red, with
    strikout if deleted

- References to syntax non-terminals in the text should be in italics.
  
- Check for technical accuracy and completeness of the description
  . Do you understand clearly the effect of the proposal?  Are all
    cases/conditions/etc. specified clearly?
  . Avoid replicating general rules of the language.  This can cause
    doubt about where they apply.




--
This message has been scanned for viruses and dangerous content by
MailScanner, and is believed to be clean.


-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.