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 |
Basics |
- |
approved |
|
ASM-2 |
Start headings with a capital letter |
Headings |
- |
approved |
|
ASM-3 |
End headings without punctuation |
Headings |
- |
approved |
|
ASM-4 |
Use the automatic numbering |
Headings |
- |
approved |
|
ASM-5 |
Start each list item in a list with an uppercase letter |
Lists |
- |
approved |
|
ASM-6 |
Put a full stop at the end of a list item if it is a full sentence |
Lists |
- |
approved |
|
ASM-7 |
Hyperlinks to external resources |
Basics |
- |
draft |
|
ASM-8 |
List content |
Lists |
- |
approved |
|
ASM-9 |
- |
- |
- |
- |
unused |
ASM-10 |
Choose a suitable type of list |
Lists |
- |
approved |
|
ASM-11 |
Do not put punctuation or conjunctions at the end of a list item |
Lists |
- |
approved |
|
ASM-12 |
Do not include footnotes |
Basics |
- |
approved |
|
ASM-13 |
Structure of footers |
Structure |
- |
approved |
|
ASM-14 |
Definition of version number |
Basics |
- |
approved |
|
ASM-15 |
Apply appropriate styles for cross references |
Basics |
- |
approved |
|
ASM-16 |
Add a description for multiline source code |
Source code and literals |
- |
approved |
|
ASM-17 |
Note the spell check results |
Language |
- |
approved |
|
ASM-18 |
List of figures is created automatically |
Structure |
- |
approved |
|
ASM-19 |
List of tables is created automatically |
Structure |
- |
approved |
|
ASM-20 |
Delete trailing space characters |
Basics |
- |
approved |
|
ASM-21 |
Include verbal forms for expressions of provisions |
Structure |
- |
approved |
|
ASM-22 |
Use a generic ASAM specification section structure |
Structure |
- |
approved |
|
ASM-23 |
Use adoc as file extension for text documents |
Basics |
- |
approved |
|
ASM-24 |
Keep one blank line at the end of file |
Basics |
- |
approved |
|
ASM-25 |
Just add one sentence per line |
Paragraphs |
- |
approved |
|
ASM-26 |
- |
- |
- |
- |
unused |
ASM-27 |
Check to include all needed sections |
Structure |
- |
approved |
|
ASM-28 |
Make sure that all included figures are shown correctly |
Figures |
- |
approved |
|
ASM-29 |
Make sure that there are no unused figures in the repository |
Figures |
- |
approved |
|
ASM-31 |
Use the standard disclaimer |
Structure |
- |
approved |
|
ASM-32 |
Add information about registered standards |
Structure |
- |
draft |
|
ASM-33 |
Use an Oxford comma |
Language |
- |
approved |
|
ASM-34 |
- |
- |
- |
- |
unused |
ASM-35 |
- |
- |
- |
- |
unused |
ASM-36 |
- |
- |
- |
- |
unused |
ASM-37 |
Check for broken internal references |
Basics |
- |
approved |
|
ASM-38 |
Check for broken hyperlinks |
Basics |
- |
approved |
|
ASM-39 |
Define the complete section structure in the mapping file |
Structure |
- |
approved |
|
ASM-40 |
Name the mapping file index.adoc |
Structure |
- |
approved |
|
ASM-41 |
File names of deliverables |
Basics |
- |
approved |
|
ASM-42 |
- |
- |
- |
- |
unused |
ASM-43 |
Use a single backtick before and after inline literals |
Source code and literals |
- |
approved |
|
ASM-44 |
Use tables to represent sets of related pieces of information |
Tables |
- |
approved |
|
ASM-45 |
Add tables in a defined sequence |
Tables |
- |
approved |
|
ASM-46 |
- |
- |
- |
- |
unused |
ASM-47 |
- |
- |
- |
- |
unused |
ASM-48 |
Use AsciiDoc syntax for lists |
Lists |
- |
approved |
|
ASM-49 |
Use American English |
Language |
- |
approved |
|
ASM-50 |
Start text in the table header with a capital letter |
Tables |
- |
approved |
|
ASM-51 |
Use a point as decimal separator |
Numbers |
- |
approved |
|
ASM-52 |
Use a leading zero for values between -1 and 1 |
Numbers |
- |
approved |
|
ASM-53 |
Indent XML attributes in examples |
Source code and literals |
- |
approved |
|
ASM-54 |
Use AsciiDoc syntax for text documents |
Basics |
- |
approved |
|
ASM-55 |
Highlight table headers |
Tables |
- |
approved |
|
ASM-56 |
- |
- |
- |
- |
unused |
ASM-57 |
Use figures with the file type SVG |
Figures |
- |
approved |
|
ASM-58 |
- |
- |
- |
- |
unused |
ASM-59 |
Add a description for each figure |
Figures |
- |
approved |
|
ASM-60 |
- |
- |
- |
- |
unused |
ASM-61 |
Write short sentences |
Language |
- |
approved |
|
ASM-62 |
Use present tense |
Language |
- |
approved |
|
ASM-63 |
Use active voice |
Language |
- |
approved |
|
ASM-64 |
Use simple phrases |
Language |
- |
approved |
|
ASM-65 |
Use complete expressions instead of abbreviations |
Language |
- |
approved |
|
ASM-66 |
Do not use synonyms |
Language |
- |
approved |
|
ASM-67 |
Use concise phrases |
Language |
- |
approved |
|
ASM-68 |
Use 'that' for essential information |
Language |
- |
approved |
|
ASM-69 |
Use 'since' to refer to a point in time |
Language |
- |
approved |
|
ASM-70 |
Spelling of terms |
Basics |
- |
approved |
|
ASM-71 |
Use of italic markup |
Paragraphs |
- |
approved |
|
ASM-72 |
- |
- |
- |
- |
unused |
ASM-73 |
- |
- |
- |
- |
unused |
ASM-74 |
Use paragraphs to structure the text |
Paragraphs |
- |
approved |
|
ASM-75 |
Do not use manual line breaks |
Paragraphs |
- |
approved |
|
ASM-76 |
Use proper names |
Basics |
- |
approved |
|
ASM-77 |
- |
- |
- |
- |
unused |
ASM-78 |
Anchor syntax |
Basics |
- |
approved |
|
ASM-79 |
Use four space characters per indentation level for source code blocks |
Source code and literals |
- |
approved |
|
ASM-80 |
- |
- |
- |
- |
unused |
ASM-81 |
Naming conventions for files of figures |
Figures |
- |
approved |
|
ASM-82 |
- |
- |
- |
- |
unused |
ASM-83 |
Use generic ASAM specification directory structure |
Structure |
- |
approved |
|
ASM-84 |
- |
- |
- |
- |
unused |
ASM-85 |
Use AsciiDoc syntax for headings |
Headings |
- |
approved |
|
ASM-86 |
Use a maximum of five levels for headings |
Headings |
- |
approved |
|
ASM-87 |
- |
- |
- |
- |
unused |
ASM-88 |
Add multiline source code in a defined sequence |
Source code and literals |
- |
approved |
|
ASM-89 |
- |
- |
- |
- |
unused |
ASM-90 |
- |
- |
- |
- |
unused |
ASM-91 |
Include information on normative and informative content |
Structure |
- |
approved |
|
ASM-92 |
Use one folder _images |
Figures |
- |
approved |
|
ASM-93 |
Uniform cell border thicknesses |
Tables |
- |
approved |
|
ASM-94 |
Use global plantuml-format attribute |
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 |
Language |
- |
approved |
|
ASM-116 |
Use 'because' to express a reason |
Language |
- |
approved |
|
ASM-117 |
- |
- |
- |
- |
unused |
ASM-118 |
Add an alternative text for every figure with defined size |
Figures |
- |
approved |
|
ASM-119 |
Use the official names of ASAM standards |
Basics |
- |
approved |
|
ASM-120 |
Use the variable {THIS_STANDARD} to refer to the standard you are working on |
Basics |
- |
approved |
|
ASM-121 |
Formatting of special words |
Source code and literals |
- |
approved |
|
ASM-122 |
Do not use slashes for conjunctions |
Language |
- |
approved |
|
ASM-123 |
Add a comma after introductory phrases |
Language |
- |
approved |
|
ASM-124 |
- |
- |
- |
- |
unused |
ASM-125 |
Names of ASAM standards |
Basics |
- |
approved |
|
ASM-126 |
Capitalization after colons |
Language |
- |
approved |
|
ASM-127 |
Use a following zero for floating-point numbers |
Numbers |
- |
approved |
|
ASM-128 |
Storage of image sources |
Figures |
- |
approved |
|
ASM-129 |
Definition of Terms for transformation to ISO |
Headings |
- |
approved |
|
ASM-130 |
Use of +, - and ± for numbers |
Numbers |
- |
approved |
|
ASM-131 |
Use the ASAM Word template for the creation of ASAM specifications |
Basics |
- |
approved |
|
ASM-132 |
Each paragraph shall be uniquely identified |
Structure |
- |
approved |
|
ASM-133 |
Conventions for mandatory, optional, and conditional content |
Structure |
- |
approved |
|
ASM-134 |
Add figures in a defined sequence |
Figures |
- |
approved |
|
ASM-135 |
Add a description for each table |
Tables |
- |
approved |
|
ASM-136 |
Display a table header on each page |
Tables |
- |
approved |
|
ASM-137 |
Antora header syntax |
Basics |
- |
approved |
|
ASM-138 |
Document title syntax |
Basics |
- |
approved |