This guide distills the editorial review principles from the HPE Writing Style Guide into a concise, reusable checklist for editing and reviewing documents. It focuses on language quality, grammar, consistency, capitalization, word choice, tense, and overall clarity.

1. Language and Tone

1.1 Clarity and Simplicity

  • Write clearly, directly, and unambiguously.
  • Prefer short sentences over long or complex ones.
  • Express one idea per sentence and one topic per paragraph.
  • Remove unnecessary words, phrases, and filler.

1.2 Global Readability

  • Write for a global audience (including ESL readers).
  • Avoid idioms, slang, humor, cultural references, and figures of speech.
  • Prefer words with a single, literal meaning.
  • Use American English spelling consistently.

1.3 Positive and Direct Language

  • Prefer positive phrasing over negative phrasing.
  • Avoid vague or absolute terms (for example: always, never, all) unless technically accurate.
  • Avoid hedging language such as should when a direct instruction is clearer.

2. Grammar and Sentence Structure

2.1 Voice

  • Use active voice by default, especially in instructions and procedures.
  • Use passive voice only when the actor is unknown or unimportant.

2.2 Tense

  • Use present tense for general statements and procedures.
  • Use past tense only for historical context.
  • Use future tense only when describing future behavior or outcomes.

2.3 Subject–Verb Agreement

  • Ensure verbs agree with their subjects in number and person.
  • Watch for agreement issues caused by long phrases or parenthetical text.

2.4 Pronouns

  • Ensure pronouns clearly refer to a single antecedent.
  • Avoid ambiguous pronoun references.
  • Use gender‑neutral pronouns (they, them, their) when referring to a generic person.
  • Avoid third‑person references such as customers, users, or clients. Write in the second person wherever possible.

3. Consistency

3.1 Terminology

  • Use the same term for the same concept throughout the document.
  • Avoid switching between synonyms for the same thing.
  • Do not mix informal and formal terminology.

3.2 Style and Formatting

  • Apply capitalization, punctuation, and formatting rules consistently.
  • Ensure lists, headings, tables, and examples follow the same structure and style.
  • Use bold formatting for Tab name, Window name, Screen name, navigation path (example, Setup > Account), and Dates.

3.3 Numbers and Units

  • Be consistent in how numbers are written (numerals vs. words).
  • Use the same unit system and precision throughout a section.

3.4 Alert Formatting

  • Use the following code formatting for the various sections:

  • Note:

  • Warning:

  • Caution:

  • Information:

  • Recommendation:

3.5 Table Formatting Rules

When adding tables to this document:

  • Use HTML tables only. Do not use Markdown pipe (|) tables.
  • All tables must follow the exact structural format shown below, regardless of the content.
  • The number of rows and columns may increase or decrease as needed, but the overall table structure, classes, and element order must remain unchanged.

Required table structure

  • The <table> element must include:

    • class="table table-striped"

  • The table header must:

    • Use <thead class="thead-dark">
    • Contain a <tr> row with <th> elements
    • Define column widths using the width attribute

  • The table body must:

    • Use <tbody>
    • Contain one or more <tr> rows
    • Use <td> cells for all data rows
    • Use <b> tags only where semantic emphasis is required (for example, action names)

Reference format (structure only)

ActionDeadlineDuring DeadlineImpact after Deadline
Sample ActionSample dateSample descriptionSample impact

4. Capitalization

4.1 General Rules

  • Use sentence case for:

    • Table titles and captions
    • List items
    • UI labels (unless the UI uses different casing)

  • Use title case only for:

    • Proper nouns
    • Official product, program, or event names
    • Headings and subheadings, specially Heading level two (##) and Heading level three (###)
    • All table headers

4.2 Avoid Overcapitalization

  • Do not capitalize common nouns for emphasis.
  • Avoid ALL CAPS except where required (for example, acronyms or alert labels).

5. Word Choice

5.1 Preferred Words

  • Choose simple, familiar words over complex or abstract ones.
  • Replace multi‑word phrases with single words where possible.
  • Avoid jargon unless the audience clearly understands it.

5.2 Avoid Ambiguous Words

  • Avoid words with multiple meanings when a precise alternative exists.
  • Prefer explicit verbs over vague constructions.

5.3 Avoid Verbing and Nominalization

  • Do not use nouns as verbs unless widely accepted.
  • Avoid turning verbs into nouns (for example: perform an installation → install).

6. Lists and Parallelism

6.1 Parallel Structure

  • Ensure all items in a list:
    • Use the same grammatical form
    • Use the same verb tense
    • Follow the same punctuation pattern

6.2 List Quality

  • Use lists only when there are two or more items.
  • Avoid mixing sentence fragments and complete sentences in the same list.
  • Keep list items concise and similar in length.

7. Punctuation and Mechanics

7.1 General Rules

  • Use one space after periods and colons.
  • Use the serial (Oxford) comma in lists.
  • Avoid exclamation points in technical or instructional content.

7.2 Commas and Clauses

  • Use commas to improve clarity and avoid misinterpretation.
  • Distinguish between restrictive (that) and nonrestrictive (which) clauses.

7.3 Hyphenation

  • Hyphenate compound adjectives before a noun when needed for clarity.
  • Do not hyphenate adverbs ending in ‑ly.

8. UI Language and Navigation Conventions

  • Use display for screens.
  • Use appears for windows, panes, dialogs, and confirmation/notification messages.
  • Represent navigation paths using > consistently (for example: Setup > Integrations > Monitoring).
  • Preserve the exact UI text as shown in the product.
  • Before starting a new procedure/action section, start with an introduction line that describes the action and its purpose. For example: “To create a new monitoring template, follow these steps:”.

9. Editing and Review Checklist

Before finalizing a document, verify that:

  • Language is clear, concise, and globally understandable
  • Grammar, tense, and voice are consistent
  • Terminology is used consistently
  • Capitalization follows sentence‑case standards
  • Word choice is precise and unambiguous
  • Lists are parallel and well‑structured
  • Punctuation improves readability and does not distract

10. OpsRamp Terminology

Use the following preferred terms and usage rules when reviewing OpsRamp documentation. The definitions are derived from the OpsRamp Glossary.

10.1 Core Platform Entities

  • Account: Use for a tenant access entity within an organization (partner or client). Do not use tenant unless you also define it as an account.
  • Partner: Use for the top-level entity in the multi-tenant model that manages client accounts. Avoid “parent customer” or “master customer”.
  • Client: Use for a sub-tenant of a partner that operates independently. Avoid “child tenant”.
  • Resource: Use for any monitored IT component (server, application, network device, etc.). Avoid mixing with “asset” unless the context is inventory/discovery.
  • Resource Group: Use for a managed collection of resources (type/location/workload). Avoid using Group when you mean Resource Group.
  • Group: Use for a logical collection of related resources used for bulk management (permissions/policies/automation). Distinguish from Resource Group if both are used in the same doc.

10.2 Monitoring, Signals, and Lifecycle

  • Metric: Use for a measurable data point collected from infrastructure components. Avoid “measurement” or “stat” unless you keep Metric as the primary term.
  • Monitor: Use for the mechanism that detects conditions and generates events/alerts (do not interchange with template).
  • Monitoring Template / Template: Use for a predefined monitoring configuration specifying metrics, collection frequency, and alert conditions for a resource type. When ambiguous, write Monitoring Template on first use.
  • Thresholds: Use for predefined metric limits that trigger alerts when exceeded. Avoid “limits” unless you also mention thresholds.
  • Event: Use for a system-generated notification when a monitor detects a condition; events are processed to create alerts. Avoid “alarm” as a synonym.
  • Alert / Alerting: Use for the processed entity generated from monitor conditions; alerts can trigger escalations and incidents. Do not use “incident” when you mean an alert.
  • Incident: Use for a critical issue created as part of alert escalation and tracked in Event & Incident Management / Service Desk context. Distinguish from “event” and “alert”.

10.3 Integrations and Data Collection

  • Integration: Use for a connection enabling data exchange with external systems (REST APIs, Webhooks, email ingestion). Avoid calling everything a “connector” unless it is the connector module.
  • Collector Profiles: Use for predefined configurations that define how collection agents gather and transmit monitoring data.
  • OpsRamp Agent: Capitalize as shown.
  • OpsRamp Gateway: Capitalize as shown.
  • NextGen Gateway: Capitalize as shown.
  • Classic Gateway: Capitalize as shown.
  • Windows Gateway: Capitalize as shown.

10.4 UI and Visualization

  • Topology / Network Topology: Use for structured mapping/visual representation of components and relationships. Avoid mixing “map” and “topology” in the same section without defining the distinction.
  • Service Map: Capitalize as shown.

10.5 Operations, Governance, and Automation

  • Role-Based Access Control (RBAC): Use for access restrictions by roles/permissions. Do not expand as “role based access” in headings; keep the hyphenated form in prose.

10.6 Review Rules

  • Use the exact glossary term for the concept (for example, Event → Alert → Incident are distinct lifecycle objects).
  • Use OpsRamp Agent and OpsRamp Gateway as product-component names (do not shorten to agent/gateway unless the component is already established in that section).
  • Prefer Monitoring Template when “template” could mean something else (policy template, email template, etc.).

11. Acronyms and Abbreviations

Use the following acronyms and abbreviations during editorial review. Ensure that the first occurrence of each acronym or abbreviation on a page is written in full, followed by the acronym in parentheses (for example, Application Programming Interface (API)). From the second occurrence onward, use only the abbreviated form on that page. Apply this rule separately to each page. Do not assume prior definition from linked or referenced pages.

  • API: Application Programming Interface
  • CMDB: Configuration Management Database
  • CPU: Central Processing Unit
  • CVE: Common Vulnerabilities and Exposures
  • DBA: Database Administrator
  • DHCP: Dynamic Host Configuration Protocol
  • DNS: Domain Name System
  • EOL: End-of-life
  • FPR: False Positive Rate
  • FTP: File Transfer Protocol
  • FTPS: File Transfer Protocol Secure
  • G1: Monitor version for Agent. All existing monitors are G1 monitors. G1 Agents have Linux versions below 3.9.9-1 and Windows versions below 5.99.0022.
  • G2: Monitor version for Agent. G2 Agents have Linux versions above 3.9.9-1 and Windows versions above 5.99.0022. The G2 Agent was introduced in release 7.0.
  • HDD: Hard Disk Drive
  • HTTP: Hypertext Transfer Protocol
  • HTTPS: Hypertext Transfer Protocol Secure
  • ICMP: Internet Control Message Protocol
  • IDE: Integrated Development Environment
  • IP: Internet Protocol Address
  • IPs: Internet Protocol Addresses
  • IPsec: Internet Protocol Security
  • JSON: JavaScript Object Notation
  • ML: Machine Learning
  • MSP: Managed Service Provider
  • NAS: Network-attached Storage
  • NFS: Network File System
  • NIC: Network Interface Controller
  • NLA: Network-level Authentication
  • NMS: Network Management System
  • NTP: Network Time Protocol
  • OID: Object Identifier
  • OOM: Out of Memory
  • OpsQ: OpsRamp Event Management Engine
  • OSPF: Open Shortest Path First Protocol
  • OVA: Open Virtual Machine Appliance
  • PCI DSS: Payment Card Industry Data Security Standard
  • PII: Personal Identifiable Information
  • POD: Point of Delivery
  • RAM: Random Access Memory
  • RBA: Role-based Access
  • RBAC: Role-based Access Control
  • RCA: Root Cause Analysis
  • RDP: Remote Desktop Protocol
  • REST: Representational State Transfer
  • RTT: Roundtrip Time
  • SAN: Storage Area Network
  • SFTP: SSH File Transfer Protocol / Secure File Transfer Protocol
  • SIP: Session Initiation Protocol
  • SMS: Short Message Service
  • SMTP: Simple Mail Transfer Protocol
  • SMTPS: Simple Mail Transfer Protocol Secure
  • SNMP: Simple Network Management Protocol
  • SRE: Site Reliability Engineer
  • SSH: Secure Shell
  • SSL: Secure Sockets Layer
  • SSO: Secure Sign-on
  • STP: Spanning Tree Protocol
  • TCP: Transmission Control Protocol
  • TLS: Transport Layer Security
  • VPN: Virtual Private Network
  • WAN: Wide Area Network
  • WMI: Windows Management Instrumentation
  • XML: Extensible Markup Language

12. Terminology Validation

When reviewing content, enforce the use of standard OpsRamp terminology.

12.1 Allowed Glossary Terms

Use the following terms exactly as written:

Account
Alert
Alerting
Alert Correlation
Alert Escalation
Auto-Monitoring

Client
Cloud Monitoring
Collector Profiles
Connector
Curated Dashboards

Dashboard

Escalation
Event
Event Correlation

First Response

Group

Incident
Inference Model
Integration

Logs

Metric
Monitoring Integrations
Monitoring Template
Monitoring

Network Topology
NetFlow
Notification

OpsRamp Agent
OpsRamp Gateway
OpsRamp Platform

Partner
Patch Management
Policy Management

Remote Console
Reporting Apps
Reports
Resource
Resource Group
Role-Based Access Control (RBAC)

Service Desk
Service Map
Synthetic Monitoring

Template
Thresholds
Topology
Topology Explorer
Traces

Widget
Workflow Automation

12.2 Terminology Review Rules

During editorial review:

  • Ensure the document uses only the allowed glossary terms listed above.
  • Replace non-standard or informal terms with the correct glossary term.
  • Maintain exact capitalization of glossary terms.
  • Do not introduce synonyms for defined concepts.

12.3 Common Term Corrections

Replace incorrect terms as follows:

  • tenant → Account
  • alarm → Alert
  • event alert → Alert
  • device / asset → Resource
  • resource collection → Resource Group
  • monitoring policy template → Monitoring Template
  • gateway VM → OpsRamp Gateway
  • agent → OpsRamp Agent

12.4 Lifecycle Validation

Ensure correct usage of lifecycle terms:

Event → Alert → Incident

  • Do not use these terms interchangeably.
  • Ensure correct sequence and meaning.

12.5 Copilot Review Instruction

When reviewing content:

  1. Identify terms that do not match the glossary.
  2. Suggest corrections using the allowed terms list.
  3. Ensure consistent terminology throughout the document.
  4. Flag ambiguous or inconsistent usage of platform terms.