document.txt (29742B)
1 Specification: 0003 R. Bron 2 Obsoletes: 0000 June 2020 3 4 5 Specification Style Guide 6 7 Abstract 8 9 This document describes the fundamental and unique style conventions and 10 editorial policies currently in use for the Specification Series. It offers 11 guidance regarding the style and structure of a Specification. 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 Copyright Notice 56 57 This document is licensed under a 58 Creative Commons Attribution 4.0 International License 59 60 You should have received a copy of the license along with this work. If not, 61 see <http://creativecommons.org/licenses/by/4.0/> 62 63 Bron [Page 1] 64 SD0003 Specification Style Guide June 2020 65 66 Table of Contents 67 68 1. Introduction ........................................................... 3 69 2. Key Words .............................................................. 3 70 2.1. MUST .............................................................. 3 71 2.2. MUST NOT .......................................................... 3 72 2.3. SHOULD ............................................................ 3 73 2.4. SHOULD NOT ........................................................ 3 74 2.5. MAY ............................................................... 4 75 2.6. Guidance in the use of these Imperatives .......................... 4 76 2.7. Security Considerations ........................................... 4 77 3. Specification Syle Conventions ......................................... 5 78 3.1. Language .......................................................... 5 79 3.2. Punctuation ....................................................... 5 80 3.3. DNS Names and URIs ................................................ 5 81 3.4. Capitalization .................................................... 5 82 3.5. Citations ......................................................... 6 83 3.6. Abbreviation Rules ................................................ 6 84 4. Structure of a Specification Document .................................. 7 85 4.1. First-Page header ................................................. 7 86 4.1.1. Author/Editor ................................................ 8 87 4.1.2. Organization ................................................. 8 88 4.1.3. Updates and Obsoletes ........................................ 8 89 4.2. Full Title ........................................................ 9 90 4.3. Abstract Section .................................................. 9 91 4.4. Table of Contents Section ......................................... 9 92 4.5. Body of the Document .............................................. 9 93 4.5.1. Introduction Section ........................................ 10 94 4.5.2. Requirements Language Section ............................... 10 95 4.5.3. Internationalization Considerations Section ................. 10 96 4.5.4. Security Considerations Section ............................. 10 97 4.5.5. References Section .......................................... 11 98 4.5.5.1. URIs in Specification Documents ........................ 11 99 4.5.5.2. Referencing Specification Documents .................... 12 100 4.5.5.3. Referencing Other Standards Development Organizations .. 13 101 4.6. Acknowledgements Section ......................................... 13 102 4.7. Contributors Section ............................................. 13 103 4.8. Author Information Section ....................................... 14 104 5. Security Considerations ............................................... 14 105 6. Normative References .................................................. 15 106 Acknowledgements ......................................................... 15 107 Author Information ....................................................... 15 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 Bron [Page 2] 127 SD0003 Specification Style Guide June 2020 128 129 1. Introduction 130 131 The ultimate goal of the Specification publication process is to produce 132 documents that are readable, clear, consistent, and reasonably uniform. The 133 basic formatting conventions for Specification Documents were established in 134 August 2018 [SD0000]. This document describes the fundamental and unique 135 style conventions and editorial policies for Specification Documents. It is 136 intended as a stable, infrequently updated reference for authors, editors, 137 and reviewers. 138 139 The world of technical publishing has generally accepted rules for grammar, 140 punctuation, capitalization, sentence length and complexity, parallelism, 141 etc. These generally accepted rules are to be followed within Specification 142 Documents. 143 144 2. Key Words 145 146 In many standards track documents several words are used to signify the 147 requirements in the specification. These words are often capitalized. This 148 section defines these words as they should be interpreted in Specification 149 Documents. Authors who follow these guidelines should incorporate this 150 phrase near the beginning of their document: 151 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 154 document are to be interpreted as described in SD0003. 155 156 Note that the force of these words is modified by the requirement level of 157 the document in which they are used. 158 159 2.1. MUST 160 161 This word, or the terms "REQUIRED" and "SHALL", mean that the definition is 162 an absolute requirement of the specification. 163 164 2.2. MUST NOT 165 166 This phrase, or the phrase "SHALL NOT", mean that the definition is an 167 absolute prohibition of the specification. 168 169 2.3. SHOULD 170 171 This word, or the adjective "RECOMMENDED", mean that there may exist valid 172 reasons in particular circumstances to ignore a particular item, but the full 173 implications must be understood and carefully weighed before choosing a 174 different course. 175 176 2.4. SHOULD NOT 177 178 This phrase, or the phrase "NOT RECOMMENDED", mean that there may exist 179 valid reasons in particular circumstances when the particular behavior is 180 acceptable or even useful, but the full implications should be understood 181 and the case carefully weighed before implementing any behavior described 182 with this label. 183 184 185 186 187 188 189 Bron [Page 3] 190 SD0003 Specification Style Guide June 2020 191 192 2.5. MAY 193 194 This word, or the adjective "OPTIONAL", mean that an item is truly 195 optional. One vendor may choose to include the item because a particular 196 marketplace requires it or because the vendor feels that it enhances the 197 product while another vendor may omit the same item. An implementation 198 which does not include a particular option MUST be prepared to interoperate 199 with another implementationn which does include the option, though perhaps 200 with reduced functionality. In the same vein an implementation which does 201 include a particular option MUST be prepared to interoperate with another 202 implementation which does not include the option (except, of course, for the 203 feature the option provides). 204 205 2.6. Guidance in the use of these Imperatives 206 207 Imperatives of the type defined in this section must be used with care and 208 sparingly. In particular, they MUST only be used where it is actually 209 required for interoperation or to limit behavior which has potential for 210 causing harm (e.g., limiting retransmissions). For example, they must not 211 be used to try to impose a particular method on implementors where the 212 method is not required for interoperability. 213 214 2.7. Security Considerations 215 216 These terms are frequently used to specify behavior with security 217 implications. The effects on security of not implementing a MUST or SHOULD, 218 or doing something the specification says MUST NOT or SHOULD NOT be done 219 may be very subtle. Document authors should take the time to elaborate the 220 security implementations of not following recommendations or requirements 221 as most implementors will not have had the benefit of the experience and 222 discussions that produced the specification. 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 Bron [Page 4] 253 SD0003 Specification Style Guide June 2020 254 255 3. Specification Style Conventions 256 257 This Style Guide does not use the terminology as defined in section 2. 258 259 3.1. Language 260 261 The Specification publication language is English. Spelling may be either 262 American or British, as long as an individual document is internally 263 consistent. Where both American and British English spelling are used within 264 a document or cluster of documents, the text will have to be modified to be 265 consistent with American English spelling. 266 267 3.2. Punctuation 268 269 - No overstriking (or underlining) is allowed. 270 271 - When a sentence ended by a period is immediately followed by another 272 sentence, there must be two blank spaces after the period. 273 274 - A comma is used before the last item of a series, e.g., 275 276 "TCP service is reliable, ordered, and full duplex" 277 278 - When quoting literal text, punctuation is placed outside quotation marks, 279 e.g., 280 281 Search for the string "Error Found". 282 283 When quoting general text, such as general text from another Specification 284 Document, punctuation may be included within the quotation marks. 285 286 Quotation marks are not necessary when text is formatted as a block 287 quotation. 288 289 3.3. DNS Names and URIs 290 291 Angle brackets are strongly recommended around URIs, e.g., 292 293 <http://example.org/> 294 295 3.4. Capitalization 296 297 - Capitalizationn must be consistent within the document and ideally should 298 be consistent with related Specification Documents. 299 300 - Per CMOS guidelines, the major words in document titles and section titles 301 should be capitalized (this is sometimes called "title cases"). Typically, 302 all words in a title will be capitalized, except for internal articles, 303 prepositions, and conjunctions. 304 305 - Section titles that are in sentence form will follow typical sentence 306 capitalization. 307 308 - Titles of figures may be in sentence form or use title case. 309 310 311 312 313 314 315 Bron [Page 5] 316 SD0003 Specification Style Guide June 2020 317 318 3.5. Citations 319 320 - References and citations must match. That is, there must be a reference 321 for each citation used. and vice versa. 322 323 - Citations must be enclosed in square brackets (e.g., "[CITE1]"). 324 325 - A citation/reference tag must not contain spaces. 326 327 Example: "[SD0003]" rather than "[SD 0003]" 328 329 However, the proper textual naming of a Specification contains a space. 330 331 Example: "See SD 0003 for more information." 332 333 - Cross-references within the body of the document and to other documents 334 must use section numbers rather than page numbers, as pagination may change 335 per format and device. 336 337 3.6. Abbreviation Rules 338 339 Abbreviations should be expanded in document titles and upon first use in the 340 document. The full expansion of the text should be followed by the 341 abbreviation itself in parenthesis. The exception is an abbreviation that is 342 so common that the readership of Specification Documents can be expected to 343 recognize it immediately; examples include (but are not limited to) TCP, IP, 344 SNMP, and HTTP. Some cases are marginal, and the author should make the 345 final judgement, weighing obscurity agains complexity. 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 Bron [Page 6] 379 SD0003 Specification Style Guide June 2020 380 381 4. Structure of a Specification Document 382 383 A published Specification Document will largely contain the elements in the 384 following list. Some of these sections are required, as noted. Sections are 385 allowed to contain nothing but subsections. The rules for each of these 386 elements are described in more details below. 387 388 First-page header [Required] 389 Title [Required] 390 Abstract [Required] 391 Copyright Notice [Required] 392 Table of Contents [Required] 393 Body of the Document [Required] 394 1. Introduction [Required] 395 2. Requirements Language 396 3. ... 397 MAIN BODY OF THE TEXT 398 6. ... 399 7. Internationalization Considerations 400 8. Security Considerations [Required] 401 9. References 402 9.1. Normative References 403 9.2. Informative References 404 Acknowledgements 405 Contributors 406 Author Information [Required] 407 408 Within the body of the document, the order shown above is strongly 409 recommended. Exceptions may be questioned. Outside the body of the 410 document, the order above is required. The section numbers above are for 411 illustrative purposes; they are not intended to correspond to required 412 numbering in a Specification Document. 413 414 4.1. First-Page header 415 416 Headers will follow the format described in "RFC Streams, Headers, and 417 Boilerplates" [RFC5741] and it's successors. In addition, the following 418 conventions will apply. 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 Bron [Page 7] 442 SD0003 Specification Style Guide June 2020 443 444 4.1.1. Author/Editor 445 446 The determination of who should be listed as an author or editor on a 447 Specification Document is made by the stream. 448 449 The author's name (initial followed by family name) appears on the first line 450 of the heading. Some variation, such as additional initials or 451 capitalization of family name, is acceptable. Once the author has selected 452 how their name should appear, they should use that display consistently in 453 all of their documents. 454 455 The total number of authors or editors on the first page is generally limited 456 to five individuals and their affiliations. If there is a request for more 457 than five authors, the stream-approving body needs to considor if one or two 458 editors should have primary responsibility for this document, with the other 459 individuals listed in the Contributors or Acknowledgements section. There 460 must be a direct correlation of authors and editors in the document header 461 and the Authors' Information section. These are the individuals that must 462 sign off on the document and respond to inquiries. 463 464 4.1.2. Organization 465 466 The author's organization is indicated on the line following the author's 467 name. 468 469 For multiple authors, each author name appears on its own line, followed by 470 that author's organization. When more than one author is affiliated with the 471 same organization, the organization can be "factored out", appearing only 472 once following the corresponding Author lines. However, such factoring is 473 inappropriate when it would force an unacceptable reordering of author names. 474 475 If an author can not or will not provide an affiliation for any reason, 476 "Independent", "Individual Contributor", "Retired", or some other term that 477 appropriately describes the author's affiliation may be used. Alternatively, 478 a blank line may be included in the document header where no affiliation is 479 provided. 480 481 4.1.3. Updates and Obsoletes 482 483 When a Specification Document obsoletes or updates a previously published 484 Specification Document or Specification Documents, this information is 485 included in the document header. For example: 486 487 "Updates: nnnn" or "Updates: nnnn, ..., nnnn" 488 489 "Obsoletes: nnnn" or "Obsoletes: nnnn, ..., nnnn" 490 491 If the document updates or obsoletes more than one document, numbers will be 492 listed in ascending order. 493 494 495 496 497 498 499 500 501 502 503 504 Bron [Page 8] 505 SD0003 Specification Style Guide June 2020 506 507 4.2. Full Title 508 509 The title must be centered below the rest of the heading, preceded by two 510 blank lines and followed by one blank line. 511 512 Choosing a good title for a Specification Document can be a challenge. A good 513 title should fairly represent the scope and purpose of the document without 514 being either too general or too specific and lengthy. 515 516 Abbreviations in a title must generally be expanded when first encountered 517 (See section 3.6 for additional guidance on abbreviations). 518 519 It is often helpful to follow the expansion with the parenthesized 520 abbreviation, as in the following example: 521 522 Encoding Rules for the 523 Common Routing Encapsulation Extension Protocol (CREEP) 524 525 4.3. Abstract Section 526 527 Every Specification Document must have an Abstract that provides a concise 528 and comprehensive overview of the purpose and contents of the entire 529 document, to give a technically knowledgeable reader a general overview of 530 the function of the document. 531 532 Composing a useful Abstract generally requires thought and care. Usually, an 533 Abstract should begin with a phrase like "This memo ..." or "This document 534 ...". A satisfactory Abstract can often be constructed in part from material 535 within the Introduction section, but an effective Abstract may be shorter, 536 less detailed, and perhaps broader in scope than the Introduction. Simply 537 copying and pasting the first few paragraphs of the Introduction is allowed, 538 but it may result in an Abstract that is both incomplete and redundant. Note 539 also that an Abstract is not a subsitute for an Introduction; the 540 Specification Document should be self-contained as if there were no Abstract. 541 542 Similarly, the Abstract should be complete in itself. It will appear is 543 isolation in publication announcements. Therefore, the Abstract must not 544 contain citations. 545 546 4.4. Table of Contents Section 547 548 A Table of Contents (TOC) is required in all Specification Documents. It must 549 be positioned after the Copyright Notice and before the Introduction. 550 551 4.5. Body of the Document 552 553 Following the TOC is the body of the document. 554 555 Each Specification Document must include an Introduction section that (among 556 other things) explains the motivation for the Specification and (if 557 appropriate) describes the applicability of the document, e.g., whether it 558 specifies a protocol, provides a discussion of some problem, is simply of 559 interest to the Internet community, or provides a status report on some 560 activity. The body of the document and the Abstract must be self-contained 561 and separable. This may result in some duplication of text between the 562 Abstract and the Introduction; this is acceptable. 563 564 565 566 567 Bron [Page 9] 568 SD0003 Specification Style Guide June 2020 569 570 4.5.1. Introduction Section 571 572 The Introduction section should always be the first section following the 573 TOC. While "Introduction" is recommended, authors may choose alternate 574 titles such as "Overview" or "Background". These alternates are acceptable. 575 576 4.5.2. Requirements Language Section 577 578 Some document use certain capitalized words ("MUST", "SHOULD", etc.) to 579 specify precise requirement levels for technical features. Section 2 of this 580 document defines a default interpretation of these capitalized words in 581 Specification Documents. If this interpretation is used, this document must 582 be citet and included as a normative reference. Otherwise, the correct 583 interpretation must be specified in the document. 584 585 This section must appear as a part of the body of the memo (as defined by 586 this document). It must appear as part of, or subsequent to, the 587 Introduction section. 588 589 These words are considered part of the technical content of the document and 590 are intended to provide guidance to implementers about specific technical 591 features, generally governed by considerations of interopretability. 592 593 4.5.3. Internationalization Considerations Section 594 595 All documents that deal with internationalization issues should have a 596 section describing those issues. 597 598 4.5.4. Security Considerations Section 599 600 All Specification Documents must contain a section that discusses the 601 security considerations relevant to the specification. 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 Bron [Page 10] 631 SD0003 Specification Style Guide June 2020 632 633 4.5.5. References Section 634 635 The reference list is solely for recording reference entries. Introductory 636 text is not allowed. 637 638 The Specification Style allows the use of any of a variety of reference 639 styles, as long as they are used consistently within a document. However, 640 where necessary, some reference styles have been described for use within the 641 Series. See the examples in this document. 642 643 Reference lists must indicate whether each reference is normative or 644 informative, where normative references are essential to implementing or 645 understanding content of the Specification Document and informative 646 references provide additional information. When both normative and 647 informative references exist, the references section should be split into two 648 subsection: 649 650 s. References 651 652 s.1. Normative References 653 654 xxx 655 ... 656 xxx 657 658 s.2. Informative References 659 660 xxx 661 ... 662 xxx 663 664 References will generally appear in alphanumeric order by citation tag. 665 Where there are only normative or informative references, no subsection is 666 required; the top-level section should say "Normative References" or 667 "Informative References". 668 669 4.5.5.1. URIs in Specification Documents 670 671 The use of URIs in references is acceptable, as long as the URI is the most 672 stable (i.e., unlikely to change and expected to be continuously available) 673 and direct reference possible. The URI will be verified as valid during the 674 Specification Document editorial process. 675 676 If a dates URI (one that includes a timestamp for the page) is available for 677 a referenced web page, its use is required. 678 679 Note that URIs may not be the sole information provided for a reference 680 entry. 681 682 683 684 685 686 687 688 689 690 691 692 693 Bron [Page 11] 694 SD0003 Specification Style Guide June 2020 695 696 4.5.5.2. Referencing Specification Documents 697 698 The following format is required for referencing Specification Documents. 699 Note the ordering for multiple authors: the format of the name of the last 700 author listed is different than that of all previous authors in the list. 701 702 For one author or editor: 703 704 [SDXXXX] Last name, First initial., Ed. (if applicable), 705 "Specification Title", Sub-series number (if applicable), 706 Specification number, Date of publication, 707 <https://finwo.nl/specifications/#.pdf> 708 709 Example: 710 711 [SD0003] Bron, R., 712 "Specification Style Guide" 713 SD 0003, June 2020 714 <https://finwo.nl/specifications/0003.pdf> 715 716 For two authors or editors: 717 718 [SDXXXX] Last name, First initial., Ed. (if applicable) 719 and First initial. Last name, Ed. (if applicable), 720 "Specification Title", Sub-series number (if applicable) 721 Specification number, Date of publication 722 <https://finwo.nl/specifications/#.pdf> 723 724 For three or more authors or editors: 725 726 [SDXXXX] Last name, First initial., Ed. (if applicable), 727 Last name, First initial., Ed. (if applicable), 728 and First initial. Last name, Ed. (if applicable), 729 "Specification Title", Sub-series number (if applicable) 730 Specification number, Date of publication 731 <https://finwo.nl/specifications/#.pdf> 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 Bron [Page 12] 757 SD0003 Specification Style Guide June 2020 758 759 4.5.5.3. Referencing Other Standards Development Organizations (SDOs) 760 761 The following format is suggested when referencing a document or standard 762 from another SDO in which authors are listed: 763 764 [SYMBOLIC-TAG] 765 Last name, First initial. and First initial. Last name, "Document 766 Title", Document reference number, Date of publication, <URI if 767 available>. 768 769 [W3C.REC-xml11] 770 Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., Yergeau, F., 771 and J. Cowan, "Extensible Markup Language (XML) 1.1 (Second 772 Edition)", W3C Recommendation REC-xml11-20060816, August 2006, 773 <http://www.w3.org/TR/2006/REC-xml11-20060816>. 774 775 Note that the order of authors in the list is the same as order shown on the 776 actual document and that the common, abbreviated form of SDO is used. 777 778 Alternatively, when no list of authors is available, the following format is 779 recommended: 780 781 [SYMBOLIC-TAG] Organization, "Document Title", Document reference number, 782 Date of publication, <URI if available>. 783 784 Example: 785 786 [IEEE802.1Q] IEEE, "Local and Metropolitan Area Networks -- Media Access 787 Control (MAC) Bridges and Virtual Bridged Local Area 788 Networks", IEEE Std 802.1Q-2011, August 2011, 789 <http://standards.ieee.org/findstds/standard/ 790 802.1Q-2011.html>. 791 792 4.6. Acknowledgements Section 793 794 This optional section may be used instead of, or in addition to, a 795 Contributors section. It is often used by authors to publicly thank those 796 who have provided feedback regarding a document and to note any documents 797 from which text was borrowed. 798 799 4.7. Contributors Section 800 801 This optional section acknowledges those who have made significant 802 contributions to the document. 803 804 In a similar fashion to the Author Information section, the determination 805 of who should be listed as a contributor is made by the stream. 806 807 The Contributors section may include brief statements about the nature of 808 particular contributions ("Sam contributed Section 3"), and it may also 809 include affiliations of listed contributors. At the descretionnn of the 810 author(s), contact addresses may also be included in the Contributors 811 section, for those contributors whose knowledge makes them useful for future 812 contacts for information about the Specification Document. The format of any 813 contact information should be similar to the format of information in the 814 Author Information section. 815 816 817 818 819 Bron [Page 13] 820 SD0003 Specification Style Guide June 2020 821 822 4.8. Author Information Section 823 824 This required section gives contact information for the author(s) listed in 825 the first-page header. 826 827 Contact information must include a long-lived email address and optionally 828 may include a postal address, telephone number, and/or Public PGP key. If 829 the postal address is included, it should include the country name, using the 830 English short name listed by the ISO 3166 Maintenance Agency [ISO_OBP]. The 831 purpose of this section is to (1) unambiguously define author identity (e.g., 832 the John Smith who works for FooBar Systems) and (2) provide contact 833 information for future readers who have questions and comments. 834 835 The practice of munged email addresses (i.e., altering an email address to 836 make it less readable to bots and web crawlers to avoid spam) is not 837 appropriate in an archival document series. Author contact information is 838 provided so that the readers can easily contact the author with questions 839 and/or comments. Address munging is not allowed in Specification Documents. 840 841 5. Security Considerations 842 843 This document has no security considerations. 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 Bron [Page 14] 883 SD0003 Specification Style Guide June 2020 884 885 6. Informative References 886 887 [SD0000] Bron, R., "Specification Format", SD 0000, August 2018 888 <https://finwo.nl/specifications/0000.pdf> 889 890 [RFC5741] Daigle, L., Ed., Kolkman, O., Ed., and IAB, "RFC Streams, 891 Headers, and Boilerplates", RFC 5741, December 2009, 892 <http://www.rfc-editor.org/info/rfc5741>. 893 894 [ISO_OBP] ISO, "Online Browsing Platform (OBP)", 895 <https://www.iso.org/obp/ui/>. 896 897 Acknowledgements 898 899 This document relies heavily on RFC 7322 [RFC7322]; as such, I am grateful to 900 the authors of those documents for putting their time and effort into the RFC 901 Series. 902 903 Author Information 904 905 R. Bron 906 EMail: robin@finwo.nl 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 Bron [Page 15]