Editorial guide

This document contains the ASAM Editorial Guide for technical writers and project group members. It contains editorial rules for contributing content to a project in written form.

This document covers the following aspects:

List of editorial rules

This section contains a list of the entire editorial rules. This means that all rules for AsciiDoc and Word are listed, regardless a rule is used in one or the other workflow, or both.

ID Short description Link to rule Section Link to test Status

ASM-1

Do not include version information

ASM-1

Basics

-

approved

ASM-2

Start headings with a capital letter

ASM-2

Headings

-

approved

ASM-3

End headings without punctuation

ASM-3

Headings

-

approved

ASM-4

Use the automatic numbering

ASM-4

Headings

-

approved

ASM-5

Start each list item in a list with an uppercase letter

ASM-5

Lists

-

approved

ASM-6

Put a full stop at the end of a list item if it is a full sentence

ASM-6

Lists

-

approved

ASM-7

Hyperlinks to external resources

ASM-7

Basics

-

draft

ASM-8

List content

ASM-8

Lists

-

approved

ASM-9

-

-

-

-

unused

ASM-10

Choose a suitable type of list

ASM-10

Lists

-

approved

ASM-11

Do not put punctuation or conjunctions at the end of a list item

ASM-11

Lists

-

approved

ASM-12

Do not include footnotes

ASM-12

Basics

-

approved

ASM-13

Structure of footers

ASM-13

Structure

-

approved

ASM-14

Definition of version number

ASM-14

Basics

-

approved

ASM-15

Apply appropriate styles for cross references

ASM-15

Basics

-

approved

ASM-16

Add a description for multiline source code

ASM-16

Source code and literals

-

approved

ASM-17

Note the spell check results

ASM-17

Language

-

approved

ASM-18

List of figures is created automatically

ASM-18

Structure

-

approved

ASM-19

List of tables is created automatically

ASM-19

Structure

-

approved

ASM-20

Delete trailing space characters

ASM-20

Basics

-

approved

ASM-21

Include verbal forms for expressions of provisions

ASM-21

Structure

-

approved

ASM-22

Use a generic ASAM specification section structure

ASM-22

Structure

-

approved

ASM-23

Use adoc as file extension for text documents

ASM-23

Basics

-

approved

ASM-24

Keep one blank line at the end of file

ASM-24

Basics

-

approved

ASM-25

Just add one sentence per line

ASM-25

Paragraphs

-

approved

ASM-26

-

-

-

-

unused

ASM-27

Check to include all needed sections

ASM-27

Structure

-

approved

ASM-28

Make sure that all included figures are shown correctly

ASM-28

Figures

-

approved

ASM-29

Make sure that there are no unused figures in the repository

ASM-29

Figures

-

approved

ASM-31

Use the standard disclaimer

ASM-31

Structure

-

approved

ASM-32

Add information about registered standards

ASM-32

Structure

-

draft

ASM-33

Use an Oxford comma

ASM-33

Language

-

approved

ASM-34

-

-

-

-

unused

ASM-35

-

-

-

-

unused

ASM-36

-

-

-

-

unused

ASM-37

Check for broken internal references

ASM-37

Basics

-

approved

ASM-38

Check for broken hyperlinks

ASM-38

Basics

-

approved

ASM-39

Define the complete section structure in the mapping file

ASM-39

Structure

-

approved

ASM-40

Name the mapping file index.adoc

ASM-40

Structure

-

approved

ASM-41

File names of deliverables

ASM-41

Basics

-

approved

ASM-42

-

-

-

-

unused

ASM-43

Use a single backtick before and after inline literals

ASM-43

Source code and literals

-

approved

ASM-44

Use tables to represent sets of related pieces of information

ASM-44

Tables

-

approved

ASM-45

Add tables in a defined sequence

ASM-45

Tables

-

approved

ASM-46

-

-

-

-

unused

ASM-47

-

-

-

-

unused

ASM-48

Use AsciiDoc syntax for lists

ASM-48

Lists

-

approved

ASM-49

Use American English

ASM-49

Language

-

approved

ASM-50

Start text in the table header with a capital letter

ASM-50

Tables

-

approved

ASM-51

Use a point as decimal separator

ASM-51

Numbers

-

approved

ASM-52

Use a leading zero for values between -1 and 1

ASM-52

Numbers

-

approved

ASM-53

Indent XML attributes in examples

ASM-53

Source code and literals

-

approved

ASM-54

Use AsciiDoc syntax for text documents

ASM-54

Basics

-

approved

ASM-55

Highlight table headers

ASM-55

Tables

-

approved

ASM-56

-

-

-

-

unused

ASM-57

Use figures with the file type SVG

ASM-57

Figures

-

approved

ASM-58

-

-

-

-

unused

ASM-59

Add a description for each figure

ASM-59

Figures

-

approved

ASM-60

-

-

-

-

unused

ASM-61

Write short sentences

ASM-61

Language

-

approved

ASM-62

Use present tense

ASM-62

Language

-

approved

ASM-63

Use active voice

ASM-63

Language

-

approved

ASM-64

Use simple phrases

ASM-64

Language

-

approved

ASM-65

Use complete expressions instead of abbreviations

ASM-65

Language

-

approved

ASM-66

Do not use synonyms

ASM-66

Language

-

approved

ASM-67

Use concise phrases

ASM-67

Language

-

approved

ASM-68

Use 'that' for essential information

ASM-68

Language

-

approved

ASM-69

Use 'since' to refer to a point in time

ASM-69

Language

-

approved

ASM-70

Spelling of terms

ASM-70

Basics

-

approved

ASM-71

Use of italic markup

ASM-71

Paragraphs

-

approved

ASM-72

-

-

-

-

unused

ASM-73

-

-

-

-

unused

ASM-74

Use paragraphs to structure the text

ASM-74

Paragraphs

-

approved

ASM-75

Do not use manual line breaks

ASM-75

Paragraphs

-

approved

ASM-76

Use proper names

ASM-76

Basics

-

approved

ASM-77

-

-

-

-

unused

ASM-78

Anchor syntax

ASM-78

Basics

-

approved

ASM-79

Use four space characters per indentation level for source code blocks

ASM-79

Source code and literals

-

approved

ASM-80

-

-

-

-

unused

ASM-81

Naming conventions for files of figures

ASM-81

Figures

-

approved

ASM-82

-

-

-

-

unused

ASM-83

Use generic ASAM specification directory structure

ASM-83

Structure

-

approved

ASM-84

-

-

-

-

unused

ASM-85

Use AsciiDoc syntax for headings

ASM-85

Headings

-

approved

ASM-86

Use a maximum of five levels for headings

ASM-86

Headings

-

approved

ASM-87

-

-

-

-

unused

ASM-88

Add multiline source code in a defined sequence

ASM-88

Source code and literals

-

approved

ASM-89

-

-

-

-

unused

ASM-90

-

-

-

-

unused

ASM-91

Include information on normative and informative content

ASM-91

Structure

-

approved

ASM-92

Use one folder _images

ASM-92

Figures

-

approved

ASM-93

Uniform cell border thicknesses

ASM-93

Tables

-

approved

ASM-94

Use global plantuml-format attribute

ASM-94

Figures

-

approved

ASM-95

-

-

-

-

unused

ASM-96

-

-

-

-

unused

ASM-97

-

-

-

-

unused

ASM-98

-

-

-

-

unused

ASM-99

-

-

-

-

unused

ASM-100

-

-

-

-

unused

ASM-101

-

-

-

-

unused

ASM-102

-

-

-

-

unused

ASM-103

-

-

-

-

unused

ASM-104

-

-

-

-

unused

ASM-105

-

-

-

-

unused

ASM-106

-

-

-

-

unused

ASM-107

-

-

-

-

unused

ASM-108

-

-

-

-

unused

ASM-109

-

-

-

-

unused

ASM-110

-

-

-

-

unused

ASM-111

-

-

-

-

unused

ASM-112

-

-

-

-

unused

ASM-113

-

-

-

-

unused

ASM-114

-

-

-

-

unused

ASM-115

Use 'which' for additional information

ASM-115

Language

-

approved

ASM-116

Use 'because' to express a reason

ASM-116

Language

-

approved

ASM-117

-

-

-

-

unused

ASM-118

Add an alternative text for every figure with defined size

ASM-118

Figures

-

approved

ASM-119

Use the official names of ASAM standards

ASM-119

Basics

-

approved

ASM-120

Use the variable {THIS_STANDARD} to refer to the standard you are working on

ASM-120

Basics

-

approved

ASM-121

Formatting of special words

ASM-121

Source code and literals

-

approved

ASM-122

Do not use slashes for conjunctions

ASM-122

Language

-

approved

ASM-123

Add a comma after introductory phrases

ASM-123

Language

-

approved

ASM-124

-

-

-

-

unused

ASM-125

Names of ASAM standards

ASM-125

Basics

-

approved

ASM-126

Capitalization after colons

ASM-126

Language

-

approved

ASM-127

Use a following zero for floating-point numbers

ASM-127

Numbers

-

approved

ASM-128

Storage of image sources

ASM-128

Figures

-

approved

ASM-129

Definition of Terms for transformation to ISO

ASM-129

Headings

-

approved

ASM-130

Use of +, - and ± for numbers

ASM-130

Numbers

-

approved

ASM-131

Use the ASAM Word template for the creation of ASAM specifications

ASM-131

Basics

-

approved

ASM-132

Each paragraph shall be uniquely identified

ASM-132

Structure

-

approved

ASM-133

Conventions for mandatory, optional, and conditional content

ASM-133

Structure

-

approved

ASM-134

Add figures in a defined sequence

ASM-134

Figures

-

approved

ASM-135

Add a description for each table

ASM-135

Tables

-

approved

ASM-136

Display a table header on each page

ASM-136

Tables

-

approved

ASM-137

Antora header syntax

ASM-137

Basics

-

approved

ASM-138

Document title syntax

ASM-138

Basics

-

approved