[EDITORIAL] Editorial Style Reference (Proposal)

[jpradocueva]

Editorial Style Suggestions

This document provides editorial style suggestions for the FOCUS v1.0 specifications. It was created in response to a recent discussion about the need for a consistent and professional editorial style to enhance and harmonize FOCUS technical specifications. The guidelines outlined below aim to standardize the presentation of various elements such as column names, column IDs, [glossary terms](), NORMATIVE KEYWORDS, attribute names, attribute IDs and other key components of the FOCUS documentation.

1. Column Names

   • Style: Bold, (with blank space for compound names)
   • Reasoning: Column names should be easily distinguishable for quick reference and clarity.
   • Example: Billing Account ID, Resource Name

2. Column IDs

   • Style: Italic, (without blank space for compound names, and compound words capatilized)
   • Reasoning: Italicizing the column IDs helps differentiate them from the display names and other text, making it clear when referring to specific IDs.
   • Example: BillingAccountId, ResourceName

3. Glossary Terms

   • Style: [Underlined](), and capitalized
   • Reasoning: Underlining glossary terms makes them stand out, helping readers quickly locate definitions and understand terminology.
   • Example: [Amortization](), [CommitmentDiscountId]()

4. Normative Statements (e.g., MUST, SHOULD, MAY)

   • Style: ALL CAPITALS and bold
   • Reasoning: Using all capitals for normative terms emphasizes their importance and aligns with standard practice in technical specifications to indicate requirement levels. In alignment with BCP14 [RFC2119][RFC8174].
   • Example: MUST, SHOULD, MAY

5. Descriptions and Content Constraints

   • Style: Normal text, but ensure clear headings and subheadings
   • Reasoning: These sections should remain easily readable, with clear headings for each sub-section to facilitate navigation.
   • Example:
     • Description: A name assigned to a grouping of resources or services, often used to manage access and/or cost.
     • Content Constraints:
     • Column type: Dimension
     • Feature level: Conditional

6. Attribute Names and IDs in Specifications

   • Style: Attribute Names in Bold, Attribute IDs in Italic
   • Reasoning: This approach helps in visually distinguishing between attribute names and their respective IDs.
   • Example:
     • Attribute Name: Currency Code Format
     • Attribute ID: CurrencyCodeFormat

7. Key-Value Format

   • Style: Monospaced font
   • Reasoning: Using a monospaced font for key-value pairs ensures clarity and readability, especially for JSON or code snippets.
   • Example:

     {
     "key1": "value1",
     "key2": true,
     "key3": 123
     }

8. Tables and Lists

   • Style: Use standard table formatting with clear column headings in bold.
   • Reasoning: Standard table formatting with bold headings improves readability and ensures that data is well-organized and easy to interpret.

   • Example:

     Constraint	Value
     Column type	Dimension
     Feature level	Conditional
     Allows nulls	True
     Data type	String
     Value format	Not specified

Implementation Examples

1. Column Definition

   • Column ID: BillingAccountId
   • Display Name: Billing Account ID
   • Description: A provider-assigned identifier for a billing account.
   • Content Constraints:
     • Column type: Dimension
     • Feature level: Mandatory
     • Allows nulls: False
     • Data type: String

2. Normative Statement Example

   • ChargePeriodStart MUST be present in the billing data, MUST be of type Date/Time, MUST be an [inclusive]() value, and MUST NOT contain null values.

3. Attribute Definition

   • Attributes ID: ColumnNamingAndOrdering
   • Attribute Name: Column Naming and Ordering
   • Description: Naming and ordering convention for columns appearing in billing data.

4. Glossary Usage Charge Period Start represents the [inclusive]() start date and time within a [charge period]().

The group should review these editorial guidelines and, if accepted, copy and paste them into the [FOCUS_Spec]() repository in a new file called EDITORIAL_GUIDELINES.md

[jpradocueva]

Maintainers-#476: Joaquin to update the guidelines, circulate them for final approval and add a suggestion on how to deal with important paragraphs

[jpradocueva]

See example document: 11.07.24 Example Editorial Guidelines