HPCC Writing Style Guide

This section covers the best practice information for writing and contributing to the HPCC Systems® Platform documentation.

General

We strive to maintain a consistent voice. These guidelines can help your writing match that voice.

• Use present tense, active voice. Documentation should be you speaking directly to the reader. Simply tell them what to do.

  This example sentence: "The user selects the file menu." is passive voice. You wouldn’t say it that way in a conversation.

  You should use active voice wording, such as: "Select the file menu".

  Similarly, instructions like these are active voice: "Press the button" or "Submit the file".

  Documentation is you instructing the user. Just tell them what to do.

• Be Brief and keep it simple. Be efficient with your words. Keep sentences short and concise. Keep paragraphs short as well. Use just a few sentences per paragraph. Use simple words wherever possible and try to avoid lengthy explanations.

• Consistency: Be consistent. Use the same voice across all documents. Use the same term, use the same spelling, punctuation, etc. Follow the conventions in this guide.

• When writing formal documentation that is more than a new feature announcement, do not refer to a new feature, or coming features as such, this does not hold up well over time.

  Do not refer to how things were done in the past. For example, "in the past we had to do X-Y-Z steps and now we no longer have to. This ‘new feature’ can do it in one step, Z". This only adds potential confusion. Just instruct on exactly what needs to be done now, using words efficiently as possible, so for this example just say “perform step Z”

Terms

There are many terms specific to HPCC Systems® and the HPCC Systems platform. Use the following style guide for word usage and capitalization guidelines to use when referring to system components or other HPCC-specific entities. Maintain consistent usage throughout all docs.

HPCC Systems®

Officially and legally the organizaion's name is HPCC Systems® and it is a registered trademark.

You should always refer to the platform as the HPCC Systems® platform and the registration mark ® should appear in the first and most prominent mention of the name.

While it is acceptable to use the ® anywhere in a document, it is required to be used in the first and most prominent mention - so the average reader will be aware. Any usage after that first and most prominent is optional.

Components and Tools

• HPCC Systems Platform

• Dali

• Sasha

• Thor

• hThor

• ROXIE

• DFU Server (Distributed File Utility Server)

• ESP Server (Enterprise Server Platform)

• ESP Services

• WsECL

• ECL Watch

• ECL Server

• ECLCC Server

• ECL Agent

• ECL IDE

• ECL Plug-in for Eclipse

• ECL Playground

• LDAP

• dafilesrv

• VS Code (no hyphen)

• ECL Language Extension for VS Code

• Configuration Manager (not ConfigMgr or ConfigManager)

Note: when referring to the startup command, use configmgr (always lowercase)

Other Terms

• HPCCSystems.com or http://HPCCSystems.com (do not include the www portion)

• ECL (Enterprise Control Language)

• ECL command-line interface

Note: when referring to the ECL command-line tool command, ecl is lowercase

• DFU Plus command-line interface

• cloud-native (always hyphenated when used as an adjective)

• DFU Workunits

• ECL Workunits

• Workunit

• WUID

• HPCC Systems®

• multi-node

• Superfiles, subfiles

• package map

• The username is the (usually unique) thing you type in with your password, for example: bobsmith66.

• The user name is the name of the user, the user's real-life name, for example: Bob Smith.

Common Documentation terms

Use the following conventions for these commonly used terms:

• right-click

• double-click

• drag-and-drop

• click-and-drag

• plug-in

• drop list

• bare metal (no hyphen)

• blue/green (not blue-green)

• Common Vulnerabilities and Exposures (CVEs)

Usage Instructions

• You click a link.

• You select a tab.

• You press a button.

• You check a (check)box.

Word Choices

Write up vs Write-up

Hyphenated when used as a noun. No Hyphen when used as a verb phrase.

Examples:

• Did you read the write-up?

• Would you write up the steps to reproduce?

Assure vs ensure vs insure

To “assure” a person of something is to make him or her confident of it.

According to the Associated Press style, to “ensure” that something happens is to make certain that it does, and to “insure” is to issue an insurance policy.

Other authorities, however, consider “ensure” and “insure” interchangeable. We prefer ensure when it is not talking about insurance.

If you have any questions, feel free to contact us at docfeedback@hpccsystems.com