Bluetooth Drafting Guidelines

The first page of a Bluetooth Document is the cover page. The cover page is required and is built into the templates.

Table 3.1 provides guidance on the best practices for filling out the elements of a cover page. The template will contain all elements that should be included; do not add or remove elements from the cover page.

After the cover page and before the disclaimer, there is a section covering the document’s version history and the content authors (i.e., the Acknowledgments table). In addition to these tables, a Bluetooth Document may contain a Change History section (see Section 3.2.2.2).

3.2.2.1. Document version history

The Version History table is required. The table lists three categories of information: version or draft/revision numbers, the publication dates, and comments that summarize the changes to the previous version made in each iteration. The first entry in the table contains the template version. This entry must not be removed.

The terms “version”, “draft”, and “revision” are defined as follows:

• Version: Indicates a specification adopted by the BoD and is indicated by a lowercase “v” value as defined by the Document Naming and Marking Document (DNMD) [3]. BSTS will fill in the date on which the BoD adopted the specification. If the Bluetooth Document has a Change History section, then a cross-reference to the applicable Change History section is also added. For example:

      Adopted by the Bluetooth SIG Board of Directors.
      For the change history between this version and the previous version, see Section x.y.z.

• Draft: Indicates a draft of a specification under development and is indicated by a lowercase “d” value as defined by the DNMD [3].

• Revision: Indicates an iteration of a draft and is indicated by a lowercase “r” value as defined by the DNMD [3]. During the development of a new specification, authors can add revision entries to inform readers of changes during that current specification development cycle. However, these entries are not intended to be public facing. When the Voting Draft is submitted to the BoD for adoption, all previous entries will be deleted and BSTS will enter the date on which the specification was adopted.

When inserting a Version History table entry into a previously approved or adopted document, adhere to the established sorting pattern within the document. In new documents, Version History table entries are sorted from oldest to newest.

Version History table comments should be concise, clear, and constructed as follows:

• Comments regarding changes to technical content (e.g., “Design altered to use a Control Point attribute for all write operations and clarify server behavior”) or that impact use of the document (e.g., “Removed Section 9.4, Content Control ID”) should be descriptive to ensure readers understand what changes were made in previous iterations.

• Comments regarding editorial changes or minor adjustments made in response to review comments should be summarized (e.g., “Addressed review comments from SIG Staff, Legal, BARB, and WG members”).

• Previous Version History table entries should not be modified unless approved by the group that authored the previous document. Modifications should only be made for corrections that add value, consistency, and clarity to the entries.

• Do not include hyperlinks in the Version History table.

• When Tech Pubs reviews a document, Tech Pubs will add the following review information to the Version History table:

  • For NWP documents: Tech Pubs will add a new row at the bottom of the Version History table with an incremented number, the date updated, and the phrase “SIG Staff review in accordance with the Bluetooth Drafting Guidelines.”

  • For FRD, d0.5, DIPD, d0.7, FIPD, d0.9, CR, Errata Corrections, and Voting Draft documents: Tech Pubs will not add a new row or increment the number in the Version History table. Instead, Tech Pubs will add a new paragraph to the current row in the Comments column with the phrase “SIG Staff review in accordance with the Bluetooth Drafting Guidelines.”

3.2.2.1.1. Examples of the version history table

The following two figures illustrate the Version History table from the same specification at two different points in time. The first is during specification development for v1.1 and consists of two version entries (v1.0 and v1.0.1) and multiple revision entries. The second is after the adoption of v1.1, when all of the revision entries have been replaced with a single version entry.

The required Acknowledgments table lists the names of individuals who substantially participated in the development of the document.

Individuals should be included in the Acknowledgments table if they have done one or more of the following:

Individuals should not be included in the Acknowledgments table if their participation is limited to the following:

If an individual requests to be included in the Acknowledgments table, and they or others identify activities that constitute substantial participation, then the WG should include them. After an individual is included in the Acknowledgments table at the FRD stage or any stage following, their name remains in the table through all remaining stages of specification development unless they request to be removed. For updated versions of a document, if the Acknowledgments table becomes very long, then the WG may move the table to the end of the document.

Individuals may be identified with more than one Bluetooth SIG member company if their participation occurred at different times when they represented different member companies. However, the name of each member company that the individual represents must be the same as the name listed in the Bluetooth member database. The names of the participating individuals can be listed in the order that the WG decides is appropriate.

If WG members do not agree on how to address acknowledgement scenarios not covered in these guidelines, then the WG Chair or Vice Chair will decide.

The disclaimer and copyright notices are required and appear before the Table of Contents (TOC) in the front matter in all documents. There are two versions of the disclaimer: one for specifications, and one for non-specification documents, such as informational publications (i.e., white papers) and process documents. See the Document Naming and Marking Document [3] for the full text of the disclaimer and copyright notices.

Do not make any changes in the disclaimer or copyright text. Tech Pubs will enter the copyright year during the editorial review of a document.

By default, the disclaimer and copyright text is locked. If the text requires updates, then Tech Pubs will make the changes using tracked changes. After the WG has seen the changes, Tech Pubs will unlock the text, accept the changes, then re-lock the text. If the text is not locked, notify the writer assigned to the WG.

The Contents section is required and contains the TOC. This section starts on the page that immediately follows the disclaimer and copyright notice.

The TOC includes heading levels 1 to 4 for sections in the main body of the document and appendixes. The TOC reflects the layout of the document structure and includes standard sections and headings of Bluetooth Documents. When headings are removed or changed in the document body, those changes are also reflected in the TOC.

To update the TOC, turn off track changes and use Microsoft^® Word’s automated Update Table feature and select “update entire table”. After updating the TOC, turn track changes back on so that no markup text is shown in the TOC. Do not make any changes to the TOC manually, for example, rewording headings or changing the number of heading levels.

The Language section (see Section 7.1) is required in Bluetooth templates for specifications starting at the Development phase (i.e., from the 0.7/FIPD stage onward). This section includes the Reserved for Future Use and Prohibited subsections; these are included in the appropriate templates. The Language section and its subsections are locked by default and must not be moved, changed, or deleted.

The body of a Bluetooth Document contains the primary document content. This is where information and technical requirements are provided.

To maintain external references between Bluetooth Documents and to prevent issues with test suite documents, preserve section numbers in the document body by adding new top-level sections to the end of the document body (i.e., before the Acronyms and abbreviations section) or by adding subsections. When adding new subsections, add the new subsection as the last one in the higher-level section.

If all content in a section is removed from a Bluetooth Document, then preserve the former section number. Update the former section heading with “[This section is no longer used]” (see Figure 3.1).

Figure 3.1. Placeholder for section removed from the Core Specification

The Bluetooth templates include Heading 1 through Heading 6 levels for the main body of the Bluetooth Document and Apx Heading 1 through Apx Heading 4 levels for appendixes. The TOC includes only Heading 1 through Heading 4 and Apx Heading 1 through Apx Heading 4. Do not add additional heading levels to the document or the TOC.

Text between heading levels is not required, although it may be used to provide context and improve readability. If text is included to provide a break between a section heading and its subsection headings, then the text should provide relevant information on the section and its subsections.

When writing headings, use “down style” (i.e., sentence-style) capitalization (for more information about capitalization, see Section 8.1.2). Headings are numbered for ease of reference. Decimal points (i.e., periods) separate the numerals to designate subordinate section levels. To apply the appropriate style to a heading, use the Microsoft^® Word template styles provided in the templates.

For best practices on Notes content, see Section 7.2.9.

When creating tables:

To create table captions:

To create table notes and conditional statements:

When describing the meaning of enumerated values or bits in a table, and some values or bits do not have an assigned meaning yet, write “all other values” or “all other bits” as the last entry in the table. Describe the values or bits as reserved for future use (RFU) and include RFU in the acronyms and abbreviations table. Do not include explicit ranges or numbers of bits.

The templates for 0.7 and 0.9 profile and service specifications contain a section that define the conventions for communicating a requirement in a table, as well as the conventions for indicating a cell that has no value or content. Such cells are referred to as unused table cells.

Include these conventions and add them to any specification where an unused cell appears in a table. This section of conventions should appear prominently and early in the specification so that it is clear that the conventions apply to all tables to which they might apply.

Indicate an intended absence of a value or other content with either the word “none” (without quotation marks) or a hyphen (i.e., a “minus” sign). If a WG decides, at its discretion, to use an additional form of notation in a specification’s tables—such as an ellipsis (…) to indicate a gap in a series of values—add an explanation of that notation in the specification’s section on table conventions for requirements and unused cells.

If a particular table uses notation that differs from the initially-expressed table conventions for unused cells, explain this additional notation in the introduction of the table to which it applies.

These conventions are provided for illustrative purposes only and should not be copied from these Drafting Guidelines for the purpose of adding them to a specification in development. To ensure you are using the most current iteration of these conventions, download either of the latest 0.7/0.9 templates from bluetooth.com, open the template, and copy the conventions from the document that opens.

For previously adopted specifications that use “N/A” to indicate “Not Applicable”, Working Groups are encouraged to replace “N/A” with either “none”, a hyphen, or an unused table cell—depending on whichever the Working Group deems most appropriate—and remove the “Not Applicable” (N/A) clause from the specification’s explanation of table conventions for requirements. However, a Working Group can, at its discretion, keep those occurrences in the specification rather than replacing them. In such a case, use “N/A” consistently without variations (e.g., “n/a”, “NA”, “na”). If the Working Group chooses to keep the occurrences of “N/A”, then in the specification’s table conventions for requirements, insert the following clause between the explanation for “Excluded” and “Conditional”:  “Not Applicable” (N/A)

When referencing a table:

Put large volumes of sample data in appendixes at the end of specifications. Add cross-reference links to those appendixes in the body text. Do not manually format sample data (e.g., paragraph and line spacing, word spacing, indents, etc.). To minimize the chances of introducing new errors, format data as follows:

Figure 3.2 and Figure 3.3 illustrate two of the many types of sample data used in specifications.

Figure 3.2. Example of sample data

Figure 3.3. Example of sample data

A reference to another section or element (e.g., tables, figures) within the same Bluetooth Document is an internal reference. Internal references are not listed in the References section.

A reference to another source (in whole or in part), whether it is published by the Bluetooth SIG, is an external reference. A non-Bluetooth source is referred to as an external source, while Bluetooth documents are referred to as internal sources, but both are referred to as external references.

Things to consider when adding an external source to a specification:

Example:

Any internal reference to a specific section, table, or figure within the same document should be linked to that section, table, or figure. The reference should be in parentheses and should read “(see Section X.X)”. Link formatting should only be applied to the section number; do not link “see” or “Section”. In all cases, apply the Document Hyperlink style in Microsoft^® Word to the link text (see Section 3.4).

An external reference in a Bluetooth Document includes a square-bracketed number that hyperlinks to the corresponding reference citation listed in the References section. Include the square brackets when applying the Document Hyperlink style (e.g., [1]) in Microsoft^® Word to the reference number.

There is no specific order for allocating external reference numbers to allow for any new references or document restructuring that may occur in future document versions. The numbers in the bracketed reference hyperlinks in the body of a document are generated automatically according to the order in which the references are listed in the References section. To maintain the reference numbers of existing references that are linked within the document, new references should be added to the end of the list in the References section instead of inserted at the beginning or in the middle of the list.

For a reference to a specific section in an external reference, cite the section number and heading. This helps avoid inaccurate references or nonfunctional links if section numbers change in the referenced resource.

When referencing external sources, ensure that:

Do not refer to a table or figure in an external reference by only its table or figure number. Instead, cite the text of the table or figure caption and the table or figure number in the reference.

Examples:

The type of link determines which part of the reference text contains the link—that is, the “hot” text that can be clicked to open the link target.

External references to publicly available documents published by any person or entity other than Bluetooth SIG, Inc. (Third-Party Document) are discouraged. If information in a Third-Party Document is essential within a Bluetooth Document to understand or implement the document, then the document author has two options:

When referencing an external source (such as a third-party white paper or standard) in a Bluetooth Document, the reference should be limited to the title, source, and location where it is publicly available (e.g., the URL of a public website). It might be acceptable to discuss the substance of and how to apply third-party content when referencing (not replicating) it within a Bluetooth Document, provided that the document provides accurate references to the content in the external source.

For full citations of external sources, use the standard syntax shown below, in the order shown (not all types of references will include all of these elements). This applies to both websites and printed books:

[<reference number>] <author or company name>, <“title and volume/edition/version (if applicable)”>, <month and year of publication (if applicable)>, <web link (for online publications)>

Examples:

For citations of printed books and documents, the International Standard Book Number (ISBN) and International Standard Serial Number (ISSN) are not included in the citation syntax.

Make sure all references are introduced with well-structured, complete sentences that clearly explain the purpose of the reference. Provide the exact title and version of the referenced source.

Example:

When a Bluetooth Document references concepts that are defined in another approved Bluetooth Document, reference the other Bluetooth Document for those concepts. It is permissible to summarize concepts before cross-referencing them, but do not restate the concepts. Repeating concepts in multiple documents invites inconsistency (e.g., when one document is updated, and the other is not). Similarly, if a term is originally defined in another Bluetooth Document, then reference the definition in the original Bluetooth Document.

The rule of referencing already-defined concepts instead of duplicating the text generally applies to final versions of Bluetooth Documents. For efficiency in the document creation process, draft documents might reference another document or duplicate text from another Bluetooth SIG document. It is acceptable to duplicate text in draft documents if the final version of the document contains the correct reference and additional text is removed. Note in early versions of Bluetooth Documents any text that will be removed from the final version.

Do not reference documents that are deprecated or withdrawn.

Bluetooth Documents that are X-level specifications (e.g., v1.0, v2.0) must include the “.0” in the version number, per the DNMD. Specifications and documents with a single active version do not require the “.0” (e.g., CSS v11).

Include “Bluetooth” in the reference only if “Bluetooth” is part of the specification title. Include “or later” in the reference only if a specification has released an enhancement (e.g., Version 1.1) or maintenance (e.g., Version 1.0.1) version. Do not include “or later” for a new specification that only has a Version 1.0).

Bluetooth supporting documents (such as Assigned Numbers or GSS) should be referenced generically, without a version number. The reference should include a link to the appropriate page on Bluetooth.com, as shown in the following examples.

For references to a Bluetooth specification, use the following syntax for citations in the body:

Examples:

Refer to a numbered section in another Bluetooth Document by its section number (see Section 3.2.7). References to the Bluetooth Core Specification contain additional information not included in general Bluetooth Document citations.

Examples:

For a reference to Bluetooth documents and webpages that contains a website URL, verify that the URL is valid and functional.

Examples:

Links to sections:

For the Bluetooth Core Specification [9], the “Vol”, “Part”, and “Section” words and their associated numbers or letters are included in the link text.

Example:

In all other specifications, only the section number contains the link (inserted as a cross-reference link). Apply the Document Hyperlink style to the link. Use the format “… (see Section X.Y)” for internal references that are in parentheses.

Examples:

Links to figures and tables:

In figure and table links, both the label and the figure or table number are included in the link text.

Examples:

Terms that appear in a Bluetooth Document vary by place of origin. These places can be thought of in terms of concentric circles, with each larger circle having a broader place of origin than the smaller circles.

Define or cross-reference terms in Bluetooth Documents based on the criteria in the following subsections.

Communicate Bluetooth terminology conventions to readers:

In the English language, the clearest and most concise sentences use a subject → verb → object structure. Consider the following sentence:

In this structure, the subject (the agent causing the action) acts upon or in relation to an object. Each of these three elements (the subject, the verb, and the object) can increase in complexity and still be easy to follow if they remain in this order. However, shorter sentences are easier to follow.

To help ensure that sentences are easy to follow, keep sentences to 20 words or fewer when feasible. When a sentence becomes too long, it can be difficult to understand what the sentence is trying to communicate. This is especially true of technical documents such as specifications. Sentences become long when the author tries to communicate too much information in one sentence. To shorten a sentence, the author should narrow the focus of what they are trying to communicate. Break a long sentence into two or three shorter sentences to make the information easier to follow. Often, a progression emerges, and it is easier to see how one idea or concept leads to or builds on another. However, consider whether breaking up a long sentence introduces other problems such as ambiguity (e.g., the unclear use of the pronoun “this” as in “The Controller shall do X. This applies when Y.”).

Phrases that serve to orient the reader to the content should be placed at the beginning of a sentence. Doing so also puts information into the correct logical sequence, which helps implementers comprehend the relationships and sequences involved in an implementation.

Incorrect

If encryption is enabled, then the initiating device shall pause and immediately resume encryption to produce a new encryption key after mutual authentication.

Correct

After mutual authentication when encryption is enabled, the initiating device shall pause and immediately resume encryption to produce a new encryption key.

To denote sequencing, use explicit words such as “first”, “second”, and so on, or place the sequence in a numbered list organized by the expected order of events.

To improve the overall quality of Bluetooth Documents, set objectives for what a reader should come to understand by the end of a paragraph. Then organize the sentences in the paragraph accordingly. This involves communicating a set of related requirements and organizing them according to a progression, if one is present. If a paragraph seems disjointed and jumps around from concept to concept or requirement to requirement, then do the following:

If content is conditional (e.g., an If… Then structure), then lay it out according to its logic. Describe the conditional content first and then the results that come from those conditions.

Avoid writing in passive voice. Writing in passive voice is often an attempt to put an emphasis on results or goals, to depersonalize the agent performing the action, or to sound formal or authoritative. In a sentence using the passive voice, the author switches the agent (subject) and the goal (direct object), so that the goal becomes the subject, and the agent becomes an indirect object or is removed from the sentence.

For example, instead of “we provided clean drinking water” (an example of active voice), the author writes “clean drinking water was provided” (an example of passive voice) [11].

Active voice

Passive voice

The subject and object switch places, and then the former subject—the noun responsible for the action in the sentence—is removed. Rather than being an active participant, the subject is implied; it is passive.

To accommodate this inversion of the sentence structure, the verb is modified (e.g., “was provided” instead of “provided”). Authors sometimes take changes to the verb a step further and obscure the meaning even more by turning the verb into a noun form called a nominalization, with verb duties getting passed on to a tacked-on, weaker verb. When this is done, the passive sentence “clean drinking water was provided” becomes “provision was made for clean drinking water”.

You can typically identify an instance of passive voice by naming the unnamed agent of action. To do so, add to the end of the sentence a prepositional phrase such as “by us” (for example, “clean drinking water was provided by us”).

The downside of passive voice is that it obscures cause and effect. Without an explicit subject, it is very difficult for a reader to understand the relationship between interacting elements. For example, the passive sentence “the control plane functionality is provided” is less clear than its active counterpart “the Channel Manager provides the control plane functionality”.

Using passive voice is the right choice in cases where:

Usually, the passive voice obscures meaning and should be avoided.

Authors add meaning and clarity to documents by providing detail. Adjectives are a common way to add detail to nouns. For instance, the meaning of the noun “bird” changes when the adjective “small” or “large” appears in front of the noun. In addition to adjectives, additional nouns can be used like adjectives to describe the primary noun, such as placing the noun “sea” in front of “bird” for the phrase “sea bird”.

To provide greater detail, authors sometimes stack multiple nouns together. If too many nouns are listed in succession, then readers can lose track of the noun being described. To avoid confusion, use a prepositional phrase to break up stacks greater than three nouns in length. For instance, the noun stack “endpoint descriptor parameter values” can be rewritten to “values of all endpoint descriptor parameters”. However, avoid introducing ambiguity when breaking up noun stacks. In some cases, the only option is to leave the noun stack intact.

The power of a verb is in its ability to convey meaning through action. A good verb, however, can lose much of its effectiveness if the author decides to use it as a noun. Authors usually do this to sound more formal or authoritative, such as in specifications. However, doing so typically weakens the sentence and obscures the intended meaning. Using a verb as a noun is called nominalization. The following example takes the verb “determine” and nominalizes it as “determination”.

Incorrect

The Attribute protocol makes no determination on the validity of the Part Attribute Value or the Value Offset.

Correct

The Attribute protocol does not determine the validity of the Part Attribute Value or the Value Offset.

Nominalizations are problematic for three reasons:

Do not make assurances regarding outcomes. Do not imply that compliance with a Bluetooth Document will meet any person or company’s needs.

Correct:

“When the Inquiry_Cancel command has completed, a Command Complete event shall be generated. No Inquiry_Complete event will be generated for the canceled Inquiry process.”

Incorrect:

“The network cache prevents devices from relaying previously received messages by adding all messages to a cached list.”

Correct:

“Note: By adding all messages to a cached list, devices can use the cache to identify messages the device has already received and avoid relaying those messages again.”

Avoid making statements regarding security or privacy. It is acceptable when defining a requirement that is motivated by privacy- or security-related concerns to present the requirement and include factual statements about the information that might be exposed if the requirement is not implemented. If a group or committee is aware of a privacy or security concern about a feature or function described in a Bluetooth Document, then they must immediately report it to Tech Pubs at specreview‑[email protected] for review. There might be situations where it is advised to include a warning in the document to inform readers of potential risk.

Incorrect:

“However, where privacy is a concern, the Local Name field should not be included in the Advertising Data.”

Correct:

“If the Local Name is included in the Advertising Data or Scan Response Data, then the identity of the device could be exposed and tracked.”

Correct:

“It may not be possible to use directed advertising to achieve a connection when using resolvable private addresses (RPAs). The ability to connect will depend on the capabilities of the peer device.”

Do not discuss laws or regulatory requirements in a final specification. When drafting a Bluetooth Document, Working Groups are free to discuss relevant technical considerations. If the justification of choice for a specification (or portion thereof) is a regulation of a particular jurisdiction, then discussion regarding the justification may be included in the notes and comments of draft documents. Before the final Bluetooth Document is submitted for approval, all notes and comments regarding the justification of choice must be removed. If a Working Group believes that it is necessary to include discussion of a law or regulatory requirement in a final Bluetooth Document, then SIG legal review and BoD approval is required. Submit requests for review and approval to Tech Pubs by the 0.9/CR stage.

Note that it is up to each member company to determine what laws and regulations apply to their Bluetooth products and to ensure compliance.

Incorrect:

“Regulations require data integrity and data unambiguity between the Sensor and Collector applications even outside the Bluetooth data transfer. Since some portions of the communication path between the Sensor and Collector could include devices or software that do not meet these requirements, a system called E2E-Protection may be necessary.”

Correct:

“Some portions of the communication path between the Sensor and Collector could include devices or software that do not have data integrity and data unambiguity between the Sensor and Collector applications outside the Bluetooth data transfer. If data integrity and data unambiguity is needed, then a system called E2E-Protection may be necessary.”

Do not reference the membership agreements (e.g., the Patent/Copyright License Agreement (PCLA), Bluetooth Trademark License Agreement (BTLA), Membership Commitment Agreement, etc.) or governing documents (Articles of Incorporation, Bylaws, policies, etc.).

Do not attempt to interpret or clarify the membership agreements or governing documents. These documents need to “speak for themselves”. The Bluetooth SIG does not provide legal advice or interpret the meaning of these documents for members.

Bluetooth specifications define the technical requirements for Bluetooth interoperability and provide the information needed to implement the specification. Limit content of a Bluetooth specification to the intended scope. For example, the scope of a specification is to define a set of requirements and describe how to implement the requirements. The process that a member must follow to demonstrate that their Bluetooth-enabled product complies with a specification and meets other requirements established by the Bluetooth SIG for qualification is outside the scope of the specification itself:

Do not incorporate any content (e.g., text, code snippets, images, or graphics) in a Bluetooth Document unless:

Third-party content is not licensed to the Bluetooth SIG under the membership agreements. Any use of third-party content (even if it is open source or available on the Internet) requires review and approval by Bluetooth SIG Legal of the license terms. Legal determines if the requisite rights are provided to include the content in the Bluetooth Document. Working Groups should identify any required third-party content for Tech Pubs as soon as possible, so Legal can review license terms.

Do not explain why particular methodologies are selected in prototyping or final specifications in final versions of Bluetooth Documents. Simply state whether the requirement is mandatory or optional, without further discussion.

Discussion about the decision-making process is necessary and appropriate in documents produced earlier in the specification development cycle, such as NWPs, FRDs, DIPDs, FIPDs, and 0.5 stage draft documents or in the exchange of comments during reviews of draft specifications. For example, if a WG is considering equally valid but mutually exclusive solutions to requirements, such as flooding vs. routing in Mesh, then discussion of the merits of each solution under consideration is acceptable within 0.5/DIPD stage materials. These discussions are out of scope for a published specification, which should simply state the chosen methodology.

Among the terms listed in the language conventions, “must” needs the most guidance and clarity. Use “must” only to express an indisputable statement of fact or to express a natural consequence of a previously stated requirement. Use “shall” not “must” when stating mandatory requirements. The following are examples of how to use “must”:

Use a note to call attention to a particular point, requirement, or implication or remind the reader of a previously mentioned point. A note is useful for clarifying text to which the reader ought to pay special attention. It is never to be used for text that describes or explains requirements or how to implement the document (even if the reader could implement the information). Each note must be set off in a separate paragraph and begin with “Note:”.

The following rules apply to notes:

Figure 7.1 shows an example of a note.

Figure 7.1. Example of a note

When referring to an object in the abstract, do not capitalize the object type if the term is not a defined term. For example, do not capitalize “profile”, “service”, or “specification” when they are not part of an object name or otherwise defined term.

However, there are some exceptions to this rule in Bluetooth Documents. Table 8.3 and Section 8.1.2 list capitalization styles to use for some of the most common Bluetooth terms.

If you are not sure whether to capitalize a term, and the term is not listed in the Drafting Guidelines, then contact the Tech Pubs writer assigned to your Working Group or committee, or email specreview‑[email protected].

These capitalization styles are in alignment with the more modern, friendlier tone of the “new blue” brand documented in the Bluetooth Brand Guide [6].

8.1.2.1. “Up” and “down” capitalization styles

Depending on context, two capitalization styles are used in document headings, titles, and captions: “up style” and “down style” (see Table 8.3).

8.1.2.1.1. “Up style” capitalization

Guiding principle: All major words (see the “DO capitalize” list below) are capitalized.

DO capitalize:

• The first word of the title.

• Verbs (including “is”), nouns, adverbs, adjectives, pronouns (including “its”), and prepositions that have five or more letters.

• Prepositions that are considered part of a verb (for example, the preposition “up” in “Back Up the Provisioning Database to the Cloud”).

• “That” and other conjunctions, including “when”, “where”, and “but”.

DO NOT capitalize:

• Articles such as “a”, “an”, and “the”.

• Prepositions that have four or fewer letters and that are not considered part of a verb.

8.1.2.1.2. “Down style” capitalization

(Also known as “sentence-style capitalization”.)

Guiding principle: Capitalization of headings and display text follows the conventions of capitalization in regular text sentences.

DO capitalize:

• The first word of the title or caption.

• Words that are capitalized in regular text paragraphs.

• Acronyms, initialisms, and most abbreviations.

• Words that are capitalized in field names, property names, and names of objects such as models, elements, states, and messages.

• The table or figure label and the first word of the caption text.

DO NOT capitalize:

• Common nouns, including the object type that often follows the name of an object such as a state, message, model, or element (for example, “the Generic OnOff state”).

• Verbs, nouns, prepositions, adverbs, and so forth that are not capitalized in regular text paragraphs.

8.1.2.1.3. Where to use “up style” and “down style” capitalization

Capitalize text elements in Bluetooth Documents as described in the Drafting Guidelines (see Table 8.3).

Text Element	Capitalization Style	Examples
Title	Up style
All headings (Heading 1 through Heading 6)	Down style
Body text	Down style	The Authorization Control Service (ACS) enables an AC Server to protect access to specific GATT resources by defining which GATT resources and related interactions are protected and by describing the information security controls that shall be used to interact with those resources.
Figure caption	Down style
Table caption	Down style
Table column headers	Up style

Table 8.3. Capitalization styles

The following rules pertain to regular text, table text, and lists in Bluetooth Documents.

DO capitalize:

DO NOT capitalize:

Examples:

Table 8.4 lists capitalization and format conventions for common object types that appear in Bluetooth Documents. The table documents conventions to apply to named objects. Do not apply these conventions to casual references to an object type.

Unless otherwise noted, do not capitalize the object type identifier (e.g., “event” or “command”), which is not considered part of the object name.

Unless noted in the entry, do not apply special formatting like italics to an object name.

The guiding principle for capitalization of named objects is to capitalize object names but not related concepts or generic usages.

In a formal object name reference, do not capitalize the object type or descriptor unless it is considered part of the object name (see Table 8.4). For example, reference “the ADP Client” or the “Service Discovery Protocol Database” (both “Client” and “Database” are considered part of the object name) but “the Synchronization Train packet” or the “Composition Data state” (both “packet” and “state” are not considered part of the object name).

After a named object is introduced, including both the object name and the object type identifier (e.g., “the LMP_FEATURES_RES message”), subsequent mentions within the same section do not need to include the object name if the context is clear. They can instead reference the object type (e.g., “the message”). However, it is imperative that the object referred to be unambiguous.

Examples:

Keep the following format requirements in mind when referencing named objects:

For rules pertaining to mathematical expressions, see Section 8.3.5.1.

Follow these guidelines for numbers or numerals in text.

Symbols for units of measurement in Bluetooth Documents follow the standards in the National Institute of Standards and Technology (NIST) Special Publication 330 [8]. Special Publication 330 conforms to the English text in the Bureau International des Poids et Mesures (BIPM) International System of Units (SI) brochure and is adapted to English (United States). Follow the guidance in this section when writing about units of measurement.

For units of measurement and their symbols that do not appear in NIST Special Publication 330, see Table 8.5.

Bluetooth Documents often contain mathematical expressions such as equations and other formulas. It is important to consistently use standardized syntax and style conventions for this type of content. This section provides references, basic guidelines, and examples for presenting mathematical expressions.

8.3.5.3. Examples of mathematical expressions

The following are some of the standard types of equations that are commonly used:

Example 1:

Example 2:

Example 3:

Example 4:

An article is a word that introduces a noun and indicates whether the noun is specific (“the”) or nonspecific (“a” or “an”). This section covers the following topics:

8.5.1.1. When is an article needed before a noun?

An article is required in table and figure references. An article is not required before a table or figure label and number.

Correct:

“The state is composed of the fields defined in Table 5.27.”

“Figure 2.3 shows the element-model structure for a device.”

An article is required with defined terms (such as a specific feature, protocol, service, or model). When the defined term is followed by the object type, introduce the defined term with an article. If the defined term is not followed by the object type, then an article is not required.

When a pronoun (such as “it”, “they”, or “these”) is used in place of a word to avoid repeating that word, make sure it is easy for readers to identify which word the pronoun is replacing. If in doubt, then repeat the word instead of using the pronoun.

In a long sentence that contains phrases and clauses, consider repeating the noun instead of using a pronoun, or break up the sentence into smaller, less complex sentences.

Unclear: “If the client had previously determined that the server did not have the «Service Changed» characteristic, or it determines by reading the «Database Hash» characteristic that the database has not changed, then service discovery may be skipped.”

Better: “If the client had previously determined that the server did not have the «Service Changed» characteristic, or the client determines by reading the «Database Hash» characteristic that the database has not changed, then service discovery may be skipped.”

If a clause (a part of a sentence) can be removed from the sentence without rendering that sentence incomplete, then begin the clause with “which” and set the clause off with commas. If a clause contains information that is essential to understanding the sentence, then begin the clause with “that” and do not set it off with commas.

Examples of clauses that can be removed without negatively impacting the sentence (use “which” and set off with commas):

Examples of clauses that are essential to the meaning of a sentence (use “that” and do not set off with commas):

This section provides rules for introducing and defining acronyms, initialisms, and abbreviations in body text.

Table 8.8 lists capitalization styles to use for some of the most common Bluetooth abbreviations, initialisms, and acronyms. Use the styles as shown.

The registered trademark symbol (®) must appear in the first prominent and technological use of Bluetooth. If it occurs in both a Heading 1 heading or subheading and the body of the text, it must be used in the first instance of each. Subsequent mentions in the same Heading 1 section - even in subsections - do not require the trademark.

The registered trademark symbol must also appear in any uses of the word mark in the abstract, References section, or appendixes, and must appear in the subtitle. The Bluetooth Core Specification must use the trademark symbol in the first prominent and technological use of the Bluetooth word mark in each Part, rather than in each Heading 1 section. If the first usage occurs in a heading, include the registered trademark symbol in both the heading and the next use of the word mark in the text body.

Examples

Correct

1.2 Bluetooth® Core Specification compatibility

The specification must be compatible with the Bluetooth® Core Specification v6.0.

Incorrect

1.2.1 Bluetooth Core Specification® compatibility

The specification must be compatible with the Bluetooth Core Specification v6.0.