Generic Authoring Rules Example
New Inspection and Review Process.
This is an example of Authoring Rules that authors can use when writing their specifications, then the Extreme Inspection/Spec QC process can help the authors verify that they did not break any of the rules.
See Extreme Inspection/Spec QC and Process, Entry and Exit Conditions
|
GEN.Consistency Specifications must be consistent with all other related specifications in the same document, and in all related documents {Sources, Kin and Children}.
GEN.Unambiguous All specifications must be unambiguous to the Intended Readership, as practiced or implied, for that document.
GEN.Clarity of Purpose All specification shall result in clarity to the Intended Reader regarding it's purpose or intent. Note: it is not enough that the statements are unambiguous. They must contain clarity of purpose: why is this here? “Clear enough to test”
GEN.Notes All manner of comment, notes, suggestion or ideas which are not themselves the actual engineering specification, but merely background, shall be clearly distinguished as such by using italic fonts. Note: Alternatives: your organization can choose any other method that clearly distinguishes the comments from the specification. Note: Suggested Devices: italics, ”double quotes”, Note:…, Comment:…., use of footnotes, use of separate commentary pages. GEN.Brevity All specification shall be as brief as possible, in order to successfully support their purpose, for the defined Intended Readership.
GEN.Elementary Specification statements shall be broken up into their most elementary form. Note: this is so that they each can be unambiguously cross-referenced externally. Note: an elementary specification can be referred to by its tag (or global tag), and within that, any unique combination of Parameter (for example Meter, Past) and/or Qualified (for example ”[UK, 1999]” ) may be used to refer to or distinguish an elementary idea.
GEN.Unique Specifications shall only have a single instance in the entire project documentation.
GEN.Glossary Words starting with a Capital Letter and in bold must be defined, and when you use a defined word, it must use a Capital Letter and be in bold. Note: Example: This is a True…. True: defined as: … |
GEN.ID Tags All specifications statements must have a unique and unambiguous cross-reference capability, which is stable, independently of sequence and changes. Dir: Statements may be directly tagged. Hier: Statements may be referenced by a hierarchy of tags Detail: Statements may be referenced in detail using Parameter names (like Meter, Goal) and Qualified (like [Euro, 2004]) GEN.Reuse Tagged Ideas shall be ’reused’ by cross-reference to their unique tag, or their tag and version information.
GEN.Source Specifications shall contain detailed (paragraph, unique tag level) references about their exact and detailed sources. Note use: ’Spec <- Source’ format or ’Source:……’
GEN.Hierarchy Log: Specifications shall be logically organized into a useful hierarchical structure. Struct: The tagging system shall reflect that structure (example A.B.C) Note: this may be partly done through templates. GEN.Auditability All changes to specifications shall be done in such a way as to permit us to know Who: who changed things, What: what the previous version was, Justification: perhaps even justification for the change. GEN.Risk Uncertain: The specification Author must clearly indicate any information which is uncertain or poses any risk to the project whatsoever Devices: using a variety of available devices such as {<fuzzy brackets>, ??, ?, ranges (60->70, 60±10%), suitable comments or notes}. GEN.Template The relevant electronic template shall be used, for specific headings and guidance under each heading.
GEN.Model A ’best practice’ model shall be defined and available. It shall be used to help interpret the intent of these rules in practice. Note: a competition of best practice can be popular. |
