From Diplomatic Standards
Category: Current Practices of DSC
Status: Draft Diplomatic Standard
DIS A201 CPD 003
Instructions to Discourse Documents (DIS)
Status Description: Draft
This document specifies the Current Practices for the Diplomatic Standards Community, and requests discussion and suggestions for improvements. Distribution of this document is unlimited.
Abstract
This page provides information for authors of Discourse (DIS) documents. It summarizes DIS editorial policies and formatting requirements, addresses frequently-asked questions, and serves as a model for constructing a properly formatted Discourse.
Discourse are draft documents valid for a maximum of six months and may be updated, replaced, or make obsolete by other documents at any time. It is inappropriate to use Discourse as reference material or to cite them other than a "work in progress."
Contents
|
[edit] Background on the Discourse Document Series
DIS documents, commonly known as Discourses, form an archival series of memos and informational comments of the standardization process of Diplomatic Standards. Included prominently in the Discourse series are the official specifications of all standards’ protocol suite; as a result, publications in the Discourse Category page play a significant role in the diplomatic standards process. Discourses are numbered consecutively, and these numbers provide a single unique label space for all Discourses. Discourses are published on-line in the category labelon the diplomatic standards’ website.
Each Discourse is labeled with one or more of these categories: Current Practice, Draft Diplomatic Standard, Proposed Diplomatic Standard, Diplomatic Standard, Experimental or Informational.
Discourses in the Diplomatic Standards category are finalized with the Directing Bodies approval. The Directing Bodies assign a maturity level – Draft, Proposed Diplomatic Standard, Draft Diplomatic Standard, or Standard -- to each Standards Track DIS.
In addition to the master Discourse index, there are secondary indexes for useful subsets or "sub-series" of the Discourses. Three sub-series are in use:
- STD document -- Category is Standards Track, maturity level is Proposed, Draft or Diplomatic Standard.
- CPD document -- Category is Current Practice of DSC
- INF document ( Information) -- Category is Informational
A Discourse in a sub-series is labeled with its sub-series number as well as its Discourse number.
[edit] Introduction to the Discourse Publication Process
This section contains a brief overview of the submission, review, and finalization process for Discourses.
[edit] Discourse Creation and Finalization
To be considered for publication as a Discourse, a document must first be submitted as a Draft Discourse in the online wiki under and be categorized as a Discourse and a link provided in the Community Portal. This ensures an opportunity for feedback from members of the Diplomatic Standards Community that frequent the Community Portal.
Discourse submissions may come from either a governmental or non-governmental organization including businesses and farmers or mainly from an individual.
To maintain the integrity of the Discourse document series and to avoid wasting resources, an Administrator or a Directing Member may reject an independent submission because its content is uninteresting or irrelevant, or because its editorial quality is unacceptable. An attempt to explain as clearly and completely as possible the reasons for rejection may be made available prior to deletion on the Discussion page.
Once the Discourse has been determined that an independent submission is acceptable, the document is reviewed for conflict with work in progress within the community. When its topic is closely related to an existing DSC Working Group, the Directing Bodies may request that the author coordinate with that working group.
[edit] Discourse Creation
An Administrator ensures that the document follows the Discourse rules described later in this document. The Administrator may make editorial changes to clarify readability and to provide a uniform style and format. If excessive work is required to satisfy the rules and/or to bring the Discourse up to a finalization quality, the page will be categorized as a Stub.
In practice, this process among the Directing Bodies, the Discourse Administrators, and the author(s) can be lengthy and convoluted, and the time spent on the Discourse can vary greatly.
[edit] General Discourse Policies
This section summarizes some general editorial and publication policies for Discourses. Individual policies may be modified or new policies added before the present document is revised. Discourse authors should obtain the latest Discourse editorial policy statements from the Discourse Category.
[edit] Immutability
Since the Discourses form an archival series, a DIS cannot be altered once it is finalized. To change the contents of a Discourse that is finalized, a new Discourse must be written that obsoletes the previous one.
Although Discourses are subjected to careful scrutiny by the community at large and the authors before publication, errors do sometimes creep in. For this reason, we strongly urge the authors to thoroughly review the document before finalization.
Errata for existing finalized Discourses are maintained in the Discourse Category. If you find what you believe to be an error in a DIS, consult the errata section in the Discussion page. If the error is not listed, please comment on the discussion page of the Discourse and/or on the talk pages of the authors of the document.
[edit] Not all Discourses are Standards
Eager salesmen may imply that all DISs represent official Diplomatic Standards. This is false and misleading. While some Discourses are Diplomatic Standards track documents, many have other categories and do not represent a standard of any kind.
[edit] Publication Language
The Directing Bodies consists of individuals from all areas of the world. However, English is the primary language in which Directing Bodies communicate, and English is the official publication language for Discourses.
Discourses submitted are required to meet a reasonable standard for clear and correct English.
DIS A100 specifically allows Discourses to be translated into languages other than English. This is highly desirable and useful. However, it is not possible for the Directing Bodies to certify that all such translations are accurate. Therefore, the function of the Discourse Administrators and Directing Bodies, with respect to non-English Discourses, is limited to providing pointers to non-English language Discourses.
[edit] Publication Format(s)
Discourses are published as plain text pages with any images or visual that may be suitable under the category Discourse on the Diplomatic Standards website.
[edit] Consistent Document Style
The Administrators attempt to enforce a consistent style of Discourses. To do this, the Administrators may encourage the community at large to reformat a submitted Discourse or ask the author to reformat it. Effort is minimized when the submitted document matches the style of the most recent Discourses.
Please read the rules and recommendations that are presented in the following sections of this page and look at some recent Discourses, to adopt an appropriate style.
[edit] Assignment of Discourse Numbers
DIS numbers are not assigned until very late in the process, to avoid gaps in the DIS number series.
[edit] References and Citations
A Discourse can generally contain bibliographic references to other documents, and the body will contain citations to these references if required.
Within a Discourse, references to other documents fall into two general categories: "normative" and "informative". Normative references specify documents that must be read to understand or implement the specification in the new Discourse, or which its pre-condition must be present for the specification in the new Discourse to work.
An informative reference is not normative; rather, it provides only additional information. For example, an informative reference might provide background or historical information. Material in an informative reference is not required to implement the specification in the DIS.
A Discourse must include separate lists of normative and informative references. The distinction between normative and informative references is often important.
The standardization’s process and the publication process participants need to know whether a reference to a work in progress is normative. A standards-track Discourse cannot be finalized until all of the documents that it lists as normative references have also been finalized. In practice, this often results in the simultaneous finalization of a group of interrelated Discourses.
[edit] Titles
Choosing a good title for a Discourse can be a challenge. A good title should fairly represent the scope and purpose of the document without being either too general or too specific.
Abbreviations (e.g., acronyms) in a title must generally be expanded when first encountered. The exception is abbreviations that are so common that every participant in the Directing Bodies can be expected to recognize them immediately. The Administrators will make the final judgment, weighing obscurity against complexity.
It is often helpful to follow the expansion with the parenthesized abbreviation, as in the following example: Agricultural and Food Chemistry Division (AFCD)
Authors should be aware that the title of a Discourse may be subject to policy considerations in addition to the requirement that it provide a concise summary of the document contents.
[edit] Relation to other Discourses
Sometimes a Discourse adds information on a topic discussed in a previous Discourse or completely replaces an earlier Discourse. Two terms are used for these cases: Updates and Obsoletes, respectively.
[edit] Updates
Specifies an earlier document whose contents are modified or augmented by the new document. The new document cannot be used alone; it can only be used in conjunction with the earlier document.
[edit] Obsoletes
This specifies an earlier document that is replaced by the new document. The new document can be used alone as a replacement for the obsolete document. The new document may contain revised information or all of the same information plus some new information, however extensive or brief that new information may be.
In the lists of Discourses and in the Discourse Category page (but not on the Discourses themselves because they are locked due to finalization) the following are used for older documents that were referred to by Obsoletes or Updates relations in newer documents:
Made obsolete:
Used to specify newer document(s) that replace the older document.
Updated by:
Used to specify newer document(s) that modify or augment the older document.
[edit] Authors Listed on Discourse
A small set of author names, with affiliations, may appear on the top of the page. These should be the lead author(s) who are most responsible for the actual page. When there are many contributors, the best choice will be to list the person or persons who acted as document wrieter(s) in the discussion page and soon a wiki template.
There is no rigid limit on the size of this set, but there is likely to be a discussion if the set exceeds a reasonable amount of authors, in which case the right answer will be up to the DIS Director.
- The Discourse may also include a Contributors section, listing those contributors who deserve significant credit for the document contents. The Contributors section is intended to provide a level of recognition greater than an acknowledgment. The choice of either, both, or none of Contributor and Acknowledgment sections in a particular Discourse depends upon the circumstance.
- The body of a DIS may include an Acknowledgements section, in addition to or instead of a Contributors section. An Acknowledgments section may be lengthy, and it may explain scope and nature of contributions. It may also specify affiliations.
- The Author's Contact information may be displayed at the end of the Discourse. The purpose of this is to provide contact information or future readers who have questions or comments.
- At the discretion of the author(s), contact addresses may also be included in the Contributors section for those contributors whose knowledge makes them useful future contacts for information about the Discourse.
- The DIS Director may grant exceptions to these guidelines upon specific request or in other exceptional circumstances.
[edit] General Format Rules for Discourses
This section defines the general rules governing the format of a finalized DIS.
Contributors are requested to come as close to these rules as reasonable, but in any case the Administrators will ensure they are met before finalization.
However, author attention to these rules will streamline the publication process and reduce the average finalization time. If reaching the final format requires excessive effort by the DS Community, the author will be asked to assist.
These formatting rules are intentionally incomplete in some details. They attempt to define only what is strictly necessary for uniformity and simplicity (a virtue). The general objective is to create a series of documents that are reasonably uniform and are easy to read, while accommodating a wide range of content.
[edit] General Formatting Rules
No Overstriking
No overstriking (or underlining) is allowed.
We strongly recommend that a new Discourse follow the same formatting conventions, which will be created into wiki templates. Any alternative style must meet the same level of clarity, readability, and lack of ambiguity. An author wishing to use an alternative style should discuss it with the DIS Director or the Discourse will never reach finalization.
[edit] Sections in a Discourse
A finalized DIS may contain the sections in the following list. Some of these sections are required, as noted. The order shown is also required.
- Status of [Required]
- Abstract [Required]
- Table of Contents
- Body [Required]
- Contributors
- Acknowledgments
- References
The rules for each of these sections are described below in corresponding subsections.
[edit] Top of Page
Please see the top part of this page for an example. The top of the page has the following items:
"Category: xxxxxxxxx"
Required left-justified field specifying the category of this DIS. Here xxxxxxxx may be one of: Current Practice, Draft Diplomatic Standard, Proposed Diplomatic Standard, Diplomatic Standard, Experimental or Informational.
"DIS: nnnn"
Identifies this as a DIS and specifies the DIS number, left- justified on the second line. The actual number is filled in at the last moment prior to finalization.
"CPD: nnnnn" or
"INF: nnnnn" or
"DGST: nnnnn"
One of these optional left-justified items indicates the sub- series number, if the Discourse is a member of a sub-series. The actual number is filled in at the last moment prior to finalization by the DIS Director.
"Updates: nnnn" or "Updates: nnnn, ..., nnnn"
Optional field containing a DIS number or a comma-separated list of DIS numbers that are updated by this DIS.
"Obsoletes: nnnn" or "Obsoletes: nnnn, ... , nnnn"
Optional field containing a DIS number or a comma-separated list of DIS numbers that are made obsolete by this DIS.
[edit] Status Description
All Discourse should supply a "Status Description" section that contains a word or a few sentences that describes the category of the Discourse.
A Discourse that is (re-)publishing or re-finalizing a specification produced by another non-DSC Bodies standards organization or is publishing a proprietary protocol may include the following paragraph in the Status Description section:
"This document may not be modified, and derivative works of it may not be created, except to publish it as a Discourse."
[edit] Abstract
Every Discourse must have an Abstract section. An Abstract will typically be 3-10 lines. An Abstract of more than 15 lines is generally not acceptable.
The Abstract section should provide a concise and comprehensive overview of the purpose and contents of the entire document, to give knowledgeable reader a general overview of the function of the document.
Composing a useful Abstract generally requires thought and care. A satisfactory abstract can often be constructed in part from material within perhaps an introductory section, but a good abstract will be shorter, less detailed, and perhaps broader in scope than the Introduction. Simply copying and pasting the first few paragraphs of the Introduction is tempting, but it may result in an Abstract that is both incomplete and redundant. Note also that an Abstract is not a substitute for an Introduction.
An Abstract should be complete in itself; it should not contain citations unless they are completely defined within the Abstract. Abbreviations appearing in the Abstract should generally be expanded in parentheses.
Each Discourse should have an Introduction section that (among other things) explains the motivation for the DIS and (if appropriate) describes the applicability of the document, e.g., whether it specifies a protocol, provides a discussion of some problem, is simply of interest to the DSC, or provides a status report on some activity.
All abbreviations that are used in the body must be expanded the first time they occur.
[edit] Contributors Section
This optional section lists those contributors who deserve significant credit for the document.
The Contributors section may include brief statements about the nature of particular contributions ("Mario contributed part 6") and it may also include affiliations of listed contributors. At the discretion of the author(s), contact addresses may also be included in the Contributors section, for those contributors whose knowledge makes them useful future contacts for information about the Discourse.
[edit] Acknowledgment Section
This optional section may be used instead of, or in addition to, a Contributors section, when appropriate.
[edit] References Section
Please follow the reference style used in recent Discourses; in particular, see the Reference section of any page for an example.
[edit] Distribution
Copying for free redistribution is allowed and encouraged. Inclusion of Discourse copies within other documents or collections that are distributed for a fee is allowed.
Anyone can take some DISs, put them in a book, copyright the book, and sell it. This in no way inhibits anyone else from doing the same thing, or inhibits any other distribution of the DISs. In this case, it is a courtesy to ask the DIS author(s) and to provide a copy of the final document or collection.