Guide to Publishing Standards

advertisement
ATIS Guide to Publishing Documents
[Last edited – 07/05/2016]
For more information, questions, or comments, please contact Alexandra Blasgen, ATIS Manager, Knowledge
Services, at < ablasgen@atis.org >.
1 Introduction
This Document serves as a guide for current and prospective Technical Editors/Issue Champions involved in work
in ATIS’s Committees, Forums, and other groups (e.g., TOPS Council initiatives) to prepare and edit ATIS
Documents. To that end, it talks about the most common causes of delays in the process, information on the
ATIS Document Template, and the most common errors of style, grammar, and punctuation.
This clause, along with those that follow, mirror what an ATIS Document should look like when using the Template
to produce a Document.
2 Requirements
2.1 SHALL/SHOULD/MAY
ATIS Style uses shall/must for requirements, should for recommendations, and may for optional capabilities.
If a there is a desire to provide emphasis for requirements, capitalization (i.e., SHALL, MUST, SHOULD, and MAY)
may be used. Do not italicize, bold, or underline shall, must, should, or may to provide emphasis.
When developing an American National Standard, do not use must to define a requirement, or may/might for
a recommendation. The only exceptions to this are if must and may appear in specifically quoted material (usually
from an IETF RFC) or if they are used as a natural course of language” (not a requirement or recommendation, just
informational). To make it clear that material is being quoted, it is helpful indent the text, and include the source
document.
2.2 Requirements/Recommendations Formatting
For consistency and readability across our Documents, the preferred format for requirements is:
R-1. (Required)
O-1. (Optional)
CR-1. (Conditional Requirement)
1
3 References
3.1 General Referencing Considerations
3.1.1 Lack of Availability for References
Any document listed as a Reference shall be available to the general public. Generally available is defined as
publically available via an internet source. A reference is not required to be free of charge but should not present an
unreasonable burden to the end user.
ATIS Committee Contributions shall not be used as references, as they are only available to ATIS
Members.
An address regarding where or how the reference is available – by an online store, a particular URL, or a specific
address – shall be provided in a footnote.
See also clause 4.1.
3.2 Normative & Informative
3.2.1.1 Normative References
A Normative Reference indicates a document that the ATIS Document is contingent upon; the document is
necessary and indispensable for the implementation of the Document. A listing of these documents shall be placed
in clause 2.
Normative Reference clauses shall include the following paragraph before the list of references:
The following documents contain provisions which, through reference in this text, constitute provisions of
this Document. At the time of publication, the editions indicated were valid. All documents are subject to
revision, and parties to agreements based on this Document are encouraged to investigate the possibility
of applying the most recent editions of the documents indicated below.
3.2.1.2 Informative References
An Informative Reference indicates a document is for information only or for background. In an ATIS Document,
Informative References should be listed in an annex/appendix titled Bibliography (though it MAY appear as a
subclause of clause 2 in ATIS Documents that are not American National Standards).
Informative Reference and Bibliography clauses/annexes shall include the following paragraph before the list of
references:
At the time of publication, the editions indicated were valid. All documents are subject to revision, and
users of this Document are encouraged to investigate the possibility of applying the most recent editions
of the documents indicated below.
2
3.3 Reference Formatting
Examples for different types of references:

ATIS-0x0000x.2014, Example of an ATIS American National Standard1

ATIS-0x0000x, Example of an ATIS Standard/Document.2

SDO-123a, Example of a Standard from Another Standards Developing Organization.3

Underkoffler, CA. Example of a Book Reference. Publishing House, Inc: March 2014.

Underkoffler, CA. “Example of an Online Periodical Reference,” Periodical Monthly.4

Underkoffler, CA. “Example of an Offline Periodical Reference,” Periodical Monthly. Vol. 1; No. 1. March
1, 2014.
3.4 Mentioning References including in the Reference Section in the Body
Text of a Document
In Documents, list the ATIS document by code number and year (e.g., ATIS-1000023.2014) in clauses that
have lists of references; however, in the body of the text, simply list the code number (e.g., ATIS-1000023). In
addition a numeric value (e.g., [1], [2]) can be assigned to each reference in the reference section and then be used for
citation throughout the body of the text.
The rationale is that having the full code number and year in the body of a documents complicates the
Reaffirmation (for ANS) and/or the revision process by having an in-body reference that may not be current.
This can also cause confusion to the end user reviewing the document that might contain outdated references. The
Administrative Revision Process 5 shall permit updating reference dates in the Normative/Informative
References/Bibliographies only, without touching the body of the text.
3.5 T1 References
There should be no T1 references (e.g., T1.101-2002). All current Standards have ATIS code numbers (e.g.,
ATIS-0900101.2006).
You should be aware that some older documents (especially Technical Reports, Technical Requirements, and
Technical Specifications) may have old Committee names and document code numbers that have changed over
the years where no other number is available can be used.
1
This document is available from the Alliance for Telecommunications Industry Solutions (ATIS) at< SPECIFIC URL
>.
2
This document is available from the Alliance for Telecommunications Industry Solutions (ATIS) at
< SPECIFIC URL >.
3
This document is available from the Standards Developing Organization (SDO) at < ORGANIZATION’S URL >.
4
This document is available at < PERIODICAL MONTHLY’S URL >.
5
< http://www.atis.org/legal/OP.asp >
3
4 Text Formatting
Technical Editors shall keep text formatting simple and straightforward. Use only bold, italic, and bold italic for
emphasis. Use simple number and bullet lists, wherever possible; minimize the use of multi-level bullets or
numbering once there are two sub-levels.
Any questions regarding the special text formatting should be included in the form of a comment for ATIS staff to
address upon review. .
4.1 Using Bookmarks in Microsoft Word
Use of Microsoft Word's bookmark features within a document is discouraged and they may be deleted by ATIS
prior to publication.
4.2 Clause Titles Style & Formatting
Replace “and” in clause titles with “&” and capitalize both words on either side of a slash (/):
Example: Bread, Butter, & Peanut Butter/Jelly
4.3 NOTE Formatting
Split out an informative NOTE if it’s in the middle of a paragraph or a parenthetical; this should be clear from
context that it’s not being used in normal language. “NOTE:” calls attention to a situation.
Informative NOTE formatting is simple: 9 point font, NOTES capitalized, colon, paragraph return after the NOTE
text, except in bullet or number lists.
NOTE: Like this.
5 Captions, Figures, & Tables
Many Documents contain Figures, Tables, and their associated captions. The following clauses provide information
about the formatting and listing of the information within ATIS Documents.
5.1.1 Figure Formatting
Figures SHALL be a centered graphic inserted using Word’s Insert Picture from File, in JPG, GIF, PNG, or VSD
format.
Textboxes, Word Shapes, WordArt, PowerPoint Slides, PDFs, etc., shall not be used as figures.
It is important to ensure that Figures are “In line with text”. In order to do this, select the figure, the “format” tab and
under “position”, select “In line with text”.
4
5.1.2 Table Formatting
The following formatting should be used for tables:

Centered.

Grid is either black (for captioned table) or 5% gray (for uncaptioned table, like the list of
Abbreviations & Acronyms).

Text is 9 point font with line-spacing of 2 points before and 2 points after.

Header row has a 5% gray fill and is checked in Table Properties as Repeat as header row at the top of
each page.

Header row text is bolded.

Properties | Row | Allow row to break across pages is unchecked.
5.1.3 Caption Formatting
Caption numbering SHALL be by clause number – e.g., Figure 4.1, 4.2, 4.3…; Figure 5.1, Figure 5.2, Figure 5.3…
NOTE: Annex caption numbering follows a similar pattern: Figure A.1, Table B.2, etc.
Figure and Table Captions should be generated by right-clicking on the Figure or Table and selecting the Caption
tool. Do not attempt to apply the [Caption] Style in lieu of this.
Creating new caption labels for Annexes is done by using the Caption tool, selecting the New Label button, and
typing in the new label (e.g., “Table 5.” or "Figure A."). Figure captions go below the figure; table captions go
above the table.
Remember to delete the extra space automatically inserted by Word in captions – i.e., change “Figure 4. 1” to
“Figure 4.1”.
6 Document Structure
6.1 Front Matter
The Front Matter of a document includes Title Page/Abstract, Foreword, Table of Contents/Figures/Tables,
trademarks, leadership lists, and other identified information (e.g., requirements language, history of document, joint
developers).
The committee should provide the Abstract. An abstract for a document is a sentence or short paragraph
describing what the document is/contains, usually boiled-down from the Scope, Purpose, & Application clause or
the Introduction clause.
ATIS Staff has responsibility for providing the remainder of info.
Trademark information shall be included in the front matter and provided to ATIS Staff by the company/individual
providing the Trademark.
No Committee/Forum rosters (individual or companies) or “active contributors” lists SHALL be included in the front
matter for ATIS Documents.
5
6.2 Copyrights & Trademarks
In addition is listing any (c), trademarked (TM), or registered trademark (R) program, logo, or website, within the
Front Matter of the Document. The appropriate symbol should appear next to the name on the cover and title
page; within the body of the text, it should appear with the first use of the item, with the footnote below (after
the footnote, one doesn't have to keep putting in the symbol):
ITEM is a trademark of COMPANY.
Any questions regarding the use of Trademark material should be directed to ATIS Staff.
6.3 Clauses
ATIS prefers the use of clause rather than “section” in all of its Documents.
It is preferred that the document opens with the following clauses:
1) Clause 1: Scope, Purpose, & Application.
1.1 Scope
1.2 Purpose
1.3 Application
2) Clause 2: References.
2.1 Normative References
2.2 Informative References
3) Clause 3: Definitions, Acronyms, & Abbreviations.
3.1 Definitions
3.2 Acronyms
3.3 Abbreviations
6.4 Definitions Clause & the ATIS Telecom Glossary
Any Definitions clause/Annex should contain this paragraph before the terms:
For a list of common communications terms and definitions, please visit the ATIS Telecom Glossary, which is
located at < http://www.atis.org/glossary >.
6.5 Annexes/Appendices
ATIS prefers the use of Annex rather than “Appendix” in all of its Documents.
Annexes shall be identified as either normative or informative. As noted above, Annexes that the ATIS Document is
contingent upon shall be marked as Normative and Annexes that are for information only shall be marked as
Informative.
6
7 Use of the ATIS Skeletons
ATIS Publications has built a Document Skeletons (DOCX/DOC files) based on the
recommendations, and needs gleaned from committee members, Technical Editors, and ATIS staff.
requests,
A Document Template (a Microsoft Word DOTX/DOT file) is also available for request if needed by committee
members, Technical Editors, and ATIS staff. A Document Template can be used for formatting a new document, but
is traditionally applied to reformat existing documentation. For additional information, please contact Kerri Conn
(kconn@atis.org).
7.1 Skeletons
ATIS Publishing provides two skeletons for your use depending on whether or not the document is an ANS or nonANS. The Skeletons provide boilerplate text for Front Matter, clauses 1 through 4, and an Annex sample. They can
be downloaded from < S:\ATIS DOC Training > (for ATIS staff only) or
< https://www.atis.org/01_resources/editorial_guide.asp >.
7.2 Autonumbering Clause Headers
The skeleton has autonumbering in place for the main bide of the document. Autonumbering is not currently built
into the skeleton for Annexes. To apply autonumbering styles in an Annex, insert a page break before the Annex,
style the Annex title as Heading 1 Style, unclick the number list button (this removes all numbers from H1),
and HIT UNDO ONCE (this puts back all the numbers EXCEPT for the Annex title).
There are often problems with the autonumbering getting messed up (usually with H2) – e.g., when you're in a
subclause of clause 3, and the document insists on styling your H2 as "1.1" instead of "3.1". This is almost always
fixed by re-importing the heading from the ATIS template.
There is no Heading Five+ autonumbering programmed into the template, so hard-code the clause number as
Normal Bold, then in the Paragraph dialogue box, on the Line and Page Breaks tab, check the Keep with next
box.
8 Style, Grammar, Punctuation, & Formatting
8.1 Computer Code Formatting
Computer-readable code and pseudo-code should be in 9 point Courier New, with 0/0 line-spacing.
10 Print “Howdy!”
20 GOTO 10
8.2 Use of Special Characters
Be aware that cutting and pasting between files (especially a DOCX and a DOC, and vice-versa) and changing
the font may cause some formatting of text to be lost. This is especially true of symbols and mathematical
7
equations often used in our Standards. Examples: µ, ∆, Ω, etc. Corrupted/Lost symbols will appear as a small open
square (□) in the text of the document.
8.3 Commas
ATIS Style uses the Oxford comma (also known as the “serial comma”) to avoid confusion in lists of elements: X,
Y, and Z.
When the elements of a series are long and complex or involve internal punctuation, they should be separated by
semicolons – e.g., when playing Monopoly, the players have the following game piece preference: Tom, the
Racecar; Dick, the Top Hat; and Harry, the Shoe.
8.4 Bullet & Number List Formatting
Try not to start a bullet list directly under a Heading-styled clause title. Insert a hard return.

Bullet
o
Sub-bullet

Sub-sub-bullet
Try not to start a numbered list directly under a Heading-styled clause title. You often need a space or a line of
text here, to stop auto-numbering lists from interfering with clause numbering. Insert a hard return.
1) Number
a. Sub-number
i. Sub-sub-number
All numbered lists should have an introductory line of text, or at least a hard return, between a clause title and the
start of the list, because sometimes the autonumbering headings and numbered lists interfere with one another.
8.5
Page & Section Breaks
Do not use page or section breaks unless absolutely necessary. If it is necessary to include a break (e.g.,
to include a landscape page in the document), please use the commenting tool to note that it is needed and ATIS
Staff will assist with adding the appropriate breaks.
8.6 Use of i.e., & e.g.,
i.e. is the abbreviation for the Latin phrase id est, meaning “that is.” e.g. is the abbreviation for the Latin phrase
exempli grata, meaning “for example.” They are not interchangeable.
Use a dash when an i.e., or e.g., appears at the end of a statement. Use parentheses if it appears in the middle of a
statement.
8

“…any resulting financial plan will be then executed by the proper official – i.e., the Secretary-Treasurer.”

“In this standard, all numerical values (e.g., voltages and currents) shown for test circuits are for purposes
of the specific test under consideration and may not represent actual operating conditions.”
A comma SHALL follow "i.e.," and "e.g.,".
8.7 Separate Files Included with a Standard
Sometimes, a separate file (ASN.1, TXT, XSD, XML, XLS, etc.) will be provided in addition to the Document. The
following text should be included as a NOTE (see clause 4.3) in the abstract (see clause 6.1), and as “placeholder”
text in the relevant Annex.
Annex [ALPHA], [ANNEX TITLE], of this Standard has also been formatted as a separate [TYPE OF FILE]
and electronically packaged with this standard.
The PDF of the Document and the separate file will be placed in a ZIP file, along with a TXT License
Agreement. Please contact ATIS Publications for more information.
9
Download