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