Generic Authoring Rules

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

Authoring Rules

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.