Style Guide

Modified: 09 Mar 2023 22:10 UTC

This style guide is a set of standards for producing documents within Joyent. It establishes these style standards to improve our communication, ensuring consistency within a single document and across multiple documents. There are also rules for graphics, UX features, and accessibility, to ensure all readers can understand our intentions.

It is not a perfect document. Rather, this document will continue to be updated as Joyent continues to evolve and as conventions change. This document will be maintained by the product team but should be used by all employees of Joyent as well as outside vendors writing for our brands.

In this guide, you will find rules for:

Joyent brand guidelines

Elevator pitch

Joyent, a wholly-owned subsidiary of Samsung, is a provider of modern, open cloud infrastructure as a service. We've created Triton, a cloud infrastructure solution built with the agility and flexibility to evolve with new architectures and applications while optimizing performance and driving down costs. Large enterprises use Triton to successfully run and scale cloud-based web, mobile and IOT applications at half the costs of other cloud providers.

Triton brand guidelines

Triton is the product family for Joyent's cloud offerings and services. In this section, you will learn how to refer properly to the various products and services.

The headers follow our rules for sentence case. If all words are capitalized, that is the product's proper name. For example

Triton clouds

These are the different ways to use Triton as a software: via our public cloud offering, private cloud, or a private region. Below are the formal names of those offerings as well as what components are offered.

Triton Public Cloud

Triton Public Cloud includes Triton Compute, Triton Object Storage and Triton Converged Analytics. You should not use "the" when referring to Triton Public Cloud.

When referring to the Triton Compute offering on the public cloud, use the name Triton Compute Service. When referring to the portal for accessing Triton Public Cloud available at http://my.mnx.io, use Triton portal. When possible, always link out to the direct page which is being referred to on the portal.

Triton Private Cloud

Triton Private Cloud includes Triton Compute, Triton Object Storage and Triton Converged Analytics. You should not use "the" when referring to Triton Private Cloud. This was formerly known as Triton Enterprise.

When referring to Triton Compute on the private cloud, use Triton DataCenter.

Triton Private Regions

A Triton Private Region would be used as a part of a multi-cloud strategy, particularly when a company is using a Kubernetes deployment. For example, a customer may have deployed their application on AWS but also uses a Triton Private Region.

Triton Compute

Under Triton Compute, there are several different offerings: Triton Virtual Machines, Triton Elastic Bare Metal, Triton Elastic Docker Host, and Triton for Kubernetes.

Triton Virtual Machines

Triton Virtual Machines is the service which supports hardware virtual machines (HVMs). This is the core value proposition for Triton Compute. We deliver GPGPU through hardware virtual machines.

While we offer Triton Elastic Docker Host to simplify the management of Docker containers, it is also possible to run traditional Docker hosts on top of Triton Virtual Machines. An example use-case for this scenario would be for running Triton for Kubernetes on top of a Docker host.

Triton Elastic Bare Metal

Triton Elastic Bare Metal is the service which supports infrastructure containers.

Triton Elastic Docker Host

Triton Elastic Docker Host is the service which supports individual Docker containers. There are no virtual machines in the middle, which would add additional cost and slow down the application. No clustering is required to deploy an application.

Triton for Kubernetes

Customers can use Triton for Kubernetes by following the quick start instructions in our Kubernetes on Triton - the easy way blog post, giving customers a pool of resources managed by Kubernetes on top of which you can deploy Docker containers. Eventually, this will become a managed service much like Triton Elastic Docker Host and Triton Elastic Bare Metal.

Triton for Kubernetes will eventually give customers additional supervision capabilities. This plan is in the roadmap.

Triton for Kubernetes is run on top of a Docker Engine on top of Triton Virtual Machines.

Triton Networking

Triton Networking encompasses networking services available on Triton Compute including load balancing and Triton Container Name Service.

CloudAPI

CloudAPI is manages all instances on Triton. This can be done with Triton CLI, i.e. triton, or via the Triton portal.

Autopilot Pattern

ContainerPilot

Always capitalize the "C" and "P" in ContainerPilot.

Triton Object Storage

Manta is the open source software that powers Triton Object Storage.

Triton Converged Analytics

Manta is the open source software that powers Triton Converged Analytics.

Node.js

The first time Node.js is referenced, it should be used as Node.js. Afterwards, Node and Node.js can be used interchangeably.

Samsung Private Cloud

Technically, Samsung Private Cloud (SPC) is a Samsung Private Region. However, it has colloquially been known as SPC and until further notice that practice will continue.

The Joyent voice

The Joyent voice should be confident and inspire readers to feel confident, too. That means being smart and clear, encouraging and informative, and without bravado.

Our voice should be consistent in all of our materials (technical, marketing, etc), regardless of the audience. Our tone is what can adapt to be serious or lighthearted depending on context and the anticipated state of mind of our audience.

Key tips

  1. Keep it simple. Avoid long sentences and long paragraphs. Scrolling through a long page of small chunks of information is easier to digest and much less intimidating than a shorter page containing large blocks of gray type.
  2. Think in tl;dr. The key takeaway should be obvious and noticeable. Start with the summary and then break down steps. Don't interrupt or overpower with unnecessary information. Too many distractions eliminate quick decision making.
  3. Be direct. Using pronouns can leave out important context. Don't use acronyms and jargon to replace topic clarity.

Additional considerations

The following are writing considerations to follow when editing and creating Joyent content.

Technical terms and other jargon

Many of the users coming to our products and documentation are familiar with the tools/terms/concepts which are common to our field such as VMs, the cloud, and the terminal. However, when introducing a new concept, it can be helpful to either include a short definition to put it in context or link out to an appropriate resource.

Grammar

There are several grammar checkers available online such as Reverso and Grammarly. It's always helpful to pass your content through one of these services. The services will arise issues with certain code or other markdown, but it will catch other spelling problems or grammar problems as well.

Product names

Here are the names of products we use often or commonly refer to but do not belong to us:

Docker usage

Docker should always be capitalized. When referring to the company, use the full name: Docker, Inc.

As a verb: dockerizing should be lower case.

Common term usage

Some of these words can be tricky or have multiple was of spelling them. Here's how we write them:

Term Part of speech Usage
add-on noun, adjective
add on verb
backend noun
back up verb
backup adjective, noun
CLI noun Always capitalize this acronym. When describing a CLI tool for the first time, use "command line interface."
cloud noun Only capitalize if it begins a sentence or as a part of a product name.
cloud node, CN noun Use the abbreviation sparingly. Regularly reference the full term within the document.
data center noun Two words, no hyphen.
debug verb
DNS noun Always capitalize
drop-down noun, adjective
drop down verb
e.g. This term can be used to replace "for example." Do not eliminate the periods.
email noun, verb Never hyphenate. Only capitalize at the beginning of a sentence.
email address noun Never replace this with "email ID" or "mail ID."
end user noun
end-user adjective
filename noun One word, no hyphens.
field noun This refers to form fields. Do not use "box" or "input."
FTP noun, verb
HTML noun Always capitalize
head node, HN noun Use the abbreviation sparingly, with regular references to the full name within the document.
hosting provider, cloud hosting provider noun You can also use "web hosting provider" when distinguishing a difference between Joyent's offerings and a web host.
hybrid cloud noun
i.e. This term can be used to replace "that is." Do not eliminate the periods.
infrastructure as a service, IaaS noun Use this term with technical audiences only. Spell it out on the first mention. Afterwards, use the abbreviation. Do not capitalize as IAAS or hyphenate.
internet noun Only capitalize if used at the beginning of a sentence or as a part of a product name.
IT as a service, ITaaS noun Use for technical or business-decision-maker audiences only. For general audiences, refer to the specific services, such as applying software updates, in cloud-computing. Spell it out on the first mention. Afterwards, use the abbreviation. Do not capitalize as ITAAS or hyphenate.
lifecycle noun This is one word. Do not hyphenate or include a space between "life" and "cycle."
login noun, adjective
login verb
Linux containers, LXC noun Spell it out on the first mention. Afterwards, use the abbreviation. Understand this term.
Linux containers, LXD noun Spell it out on the first mention. Afterwards, use the abbreviation. LXD depends on LXC. Understand this term.
multi-cloud adjective Always hyphenate.
online Only capitalize if this begins a sentence.
opt-in noun, adjective
opt in verb
operating system, OS noun Spell it out on the first mention. Afterwards, use the abbreviation. When plural, do not use an apostrophe, i.e. OSs.
PC noun Always capitalize.
plugin noun, verb
re-order verb
run time noun Two words, no hyphen.
signup noun, adjective
sign up verb
SSH noun, verb Always capitalize.
SSL noun Always capitalize.
Summary, tl;dr When writing for a non-US audience, always use "Summary."
up time noun Two words, no hyphen.
URL noun Always capitalize.
username noun
user-friendly adjective Always hyphenate this when used as a descriptor.
VPC, virtual private cloud noun Spell it out on the first mention along with the acronym in quotation marks, i.e. "VPC". Afterwards, use the abbreviation.
web server noun Two words, no hyphen.
website noun One word.

Common acronyms

Below is a list of acronyms and their definitions. Remember, these are common for a technical audience at Joyent, not for a business-focused or non-technical audience.

Acronym Definition
ACPI Advanced Configuration and Power Interface Specification
AHCI Advanced Host Controller Interface
CCID Integrated Circuit Card Interface Device
CPLD Complex Programmable Logic Device
DC Data center
EFI Extensible Firmware Interface
FMA Fault Management Architecture
FPGA Field Programmable Gate Array
FRU Field Replaceable Unit
GB/s Gigabits per second
GPIO General Purpose Input / Output
GPGPU General purpose graphics processing unit
HBA Host Bus Adapter
HDD Hard disk drive
HPE Hewlett Packard Enterprise
HW Hardware
IPMI Intelligent Platform Monitoring Interface
JPC MNX Public Cloud, a deprecated term for Triton
LLDP Link Layer Discovery Protocol
LLDP Link Layer Discovery Protocol
LOM Lights Out Management
MLNX Mellanox
MSI-X Extended Message Signaled Interrupts
NIC Network Interface Card
NVMe Non-volatile Memory Express
OEM Original Equipment Manufacturer
PCH Platform Controller Hub
PCIe PCI Express
PDU Power Device Unit
PMBus Power Management Bus
PSU Power Supply Unit
Phy Physical, often refers to the physical layer or interconnect of a device
RAS Reliability and Serviceability
SAS Serial Attached SCSI
SATA Serial ATA
SES SCSI Enclosure Services
SCSI Small Computer Systems Interface
SFF Small Form Factor
SGX Software Guard Extensions
SMBus System Management Bus
SPC Samsung Private Cloud
STP Spanning Tree Protocol
SSD Solid State Drive
Topo Topology
UFM Upgradable Firmware Module
USB Universal Serial Bus
VLAN Virtual LAN

Dates

These are the rules for writing dates within content:

Variables

When a variable is in place in our documentation, best practice is to name the variable with angle brackets: < and >. Here are some common variables for code examples:

Alternatively, some variables may appear with the dollar sign, such as $UUID.

Text style and UI

Follow web standards

Expect users will skim content instead of reading thoroughly. As the number of words on a page goes up, the percentage users read goes down.

When writing for the web, it's important to split content into sections with informative headings. Put the most important information at the top and the background at the bottom (inverted pyramid style).

Your content is not clear unless your users can:

Do not hard-wrap text

To preserve the semantic nature of sentences, paragraphs, and headings, it is critical that no text be hard-wrapped. Existing text that is hard-wrapped must he unwrapped upon review.

When in doubt, don’t capitalize

Default to sentence-style capitalization—capitalize only the first word of a heading or phrase and any proper nouns or names. Never Use Title Capitalization (Like This). Never Ever. To learn more, see Capitalization.

Incorrect Correct
Find a Triton Data Center Find a Triton data center
Triton Compute Customer Triton Compute customer
Limited Time Offer Limited time offer
Join Us Online Join us online

Limit uses of spaces

Use one space after punctuation (periods, question marks, and colons). Do not use two spaces.

Button style

Title case is used for all buttons. Capitalize all words except for articles (a, an, the), coordinating conjunctions (and, but, for), prepositions (at, by, from), and words that are shorter than 5 letters and not proper nouns.

Forms

When referring forms and form inputs in documentation, use "field" preceded by the name of the field. For example:

In the Create SSH Key dialog box, enter a name for your SSH key in the Key Name field and then select Create Key.

Heading style

Sentence case is used for all headings. Capitalize the first word and proper nouns, nothing else.

Link content

Avoid linking directional phrases such as "click here." Instead, wrap the link around content which is indicative of what the user will see. This can be the title of the page or a descriptive phrase.

Punctuation

Oxford comma (serial comma)

The Oxford comma (otherwise known as a serial comma) should always be used to prevent confusion, as is often created when a list has internal conjunctions or is complex in another way. It adds clarity and makes lists much easier to read.

The Oxford comma is the final comma in a list of items, before the "and" which separates the last two items. For example:

I have instances for Nginx, MySQL, InfluxDB, Jenkins, and Consul in my data center.

Trailing punctuation

Do not include leading or trailing punctuation in links with the exception of:

If the quotation mark surrounds a quote which is not a direct copy from the context, such as quoting a tweet, the quotation marks should not be included (ex: ["just like that," tweeted Wendy](link to tweet)).

Images and multimedia

Images should provide additional context for content. All images must have clear descriptions so that if the image cannot be seen, either because of website loading problems or the user's visual impairment.

Always provide accurate alt text for any element other than live text including graphics, audio, video, animations, and pictures of text. When possible, avoid using pictures of text. Describe the element to give useful context to the reader.

Provide closed-captioning or transcripts of audio and video content.

International communication

As a subsidiary of Samsung, we often must communicate with our colleagues in Korea. Additionally, Joyent has customers around the globe who come to our content with varied levels of understanding of American English and varied technical backgrounds. Keep this in mind when creating new content.

While not every culture can always be accommodated, clear articulation is key to mutual understanding.

Choose words carefully

Use simple words and phrases. When choosing a word, pick the familiar or commonly used word over the unusual or obscure. Unnecessary flair complicates translation. For example, choose "begin" over "commence" and "use" over "utilize."

Minimize abbreviations. Much like defined in the grammar section, no abbreviation or acronym should exist without defining the acronym first. The exception to this rule is very commonly used acronyms such as SSL, IBM, ATM, and PhD.

Be careful with word placement. Reduce ambiguity and increase clarity by keeping subjects and objects close to your verbs. Put conditionals such as "always" or "only" next to the word it is modifying. For example, write “you are required to provide only the following,” not “you are only required to provide the following.”

Avoid uncommon idioms and slang. Idioms and slang can greatly differ from the literal translation of the words. This makes translation difficult. For example, write "it's your turn to take action" instead of "the ball's in your court." Instead of "the alarm went off" use "the alarm turned on."

Additional resources

Accessibility

This resource is intended to help Joyent creators develop accessible products and content, however it is far from the only guideline. When in doubt, refer to the standards set by W3C.

Our content should be usable for the widest possible audience. This does not mean that everyone will understand every topic. In particular at Joyent, many of our products are for an advanced technical audience. However, writing with accessibility standards does not mean just making content easy to understand. It also means considering the organization of content to guide readers (be it visually or via screen readers, keyboard navigation, or a Braille interface).

There are a number of additional resources from which this guide was sourced.

As you write, consider the following:

Content structure creates communication

Use heading levels to communicate the hierarchy of content. Emphasize important points both visually and stylistically. Use lists and tables to demonstrate a relationship between concepts. Provide summaries for tables and use informative, concise column headings.

Directional terms such as left, right, up, down, above, and below are not useful for those who use screen-readers. If you must use directional terms, provide additional information about the location such as "title bar" or "dialog box."

Refer to our text style and UI guidelines for information on links, headers, and images.

Additional resources

Much of the codebases we create have individual licenses. Triton uses Mozilla Public License 2.0. SmartOS uses CDDL version 1.0.

Copyright notice for our works is not required but is recommended to ensure protection against innocent infringement.

Fair Use

The spirit of fair use is permitting limited use of copyrighted material without acquiring permission from the copyright holder. Examples include commentary, criticism, parody, research, scholarship, and research. The four guidelines on which it is judged:

In particular, the portion of work used is important. When using direct quotations, always cite the source. Shorter quotations are better. There's no exact measurement (10 words is safe and 100 is not), but think about the content in context. A sentence or two from an article is generally a safe bet, or up to a paragraph from a book chapter. These are suggestions, not rules.

Never directly copy an entire body of work (or a large percentage of a body of work), as that would be copyright infringement.

Visit the U.S. Copyright Office website for official guidelines on fair use.