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
- The Triton brand
- Writing in the Joyent voice
- Grammar rules
- Text style and UI
- International communication
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 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: Triton is a product, Triton clouds is not.
- Triton Public Cloud: Triton Public Cloud is the official name of the public cloud offering.
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 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.joyent.com, use Triton portal. When possible, always link out to the direct page which is being referred to on the portal.
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.
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 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 is the service which supports infrastructure containers.
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.
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 encompasses networking services available on Triton Compute including load balancing and Triton Container Name Service.
CloudAPI is manages all instances on Triton. This can be done with Triton CLI, i.e.
triton, or via the Triton portal.
Always capitalize the "C" and "P" in ContainerPilot.
Manta is the open source software that powers Triton Object Storage.
Manta is the open source software that powers Triton Converged Analytics.
The first time Node.js is referenced, it should be used as Node.js. Afterwards, Node and Node.js can be used interchangeably.
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 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.
- 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.
- 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.
- Be direct. Using pronouns can leave out important context. Don't use acronyms and jargon to replace topic clarity.
The following are writing considerations to follow when editing and creating Joyent content.
- All content such as training material, procedures, SOPs, scripts, and other documentation should be written in plain language that is as clear, simple, and forthright as possible.
- Ask yourself: does this content make sense to someone who does not work at Joyent?
- The more difficult the concept, the more important it is to break it down into smaller chunks and repeat the essential takeaways.
- A list, conceptual graphic, animation, or video may be the best way to enhance learning a concept.
- If using an image or video, there should always be text which accompanies it to explain the concept. This ensures accessibility.
- Avoid pronouns when possible. Referring to items as “it” and “things” leaves out contextual information that may have been lost to the reader.
- Using "you," the second-person singular pronoun, can help indicate when a user should be doing something directly and engage the reader. Be sure not to use "you" when the content doesn't apply to the reader.
- Use active voice rather than passive voice. Read more about that concept.
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.
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.
Here are the names of products we use often or commonly refer to but do not belong to us:
- AWS (always capitalize)
- Docker (noun, always capitalize), dockerizing (verb, never capitalize unless beginning a sentence)
- Docker, Inc. should be used when referring to the company.
- Docker Compose
- Docker Remote API
- iCloud, iPhone, iPad
- Mac, Macintosh (always capitalize the "M" when referring to the computer)
- macOS (previously known as "Mac OS X", never capitalize the "m" for the operating system)
- Prometheus or Prometheus.io
Docker should always be capitalized. When referring to the company, use the full name: Docker, Inc.
As a verb: dockerizing should be lower case.
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|
|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.|
|e.g.||This term can be used to replace "for example." Do not eliminate the periods.|
|noun, verb||Never hyphenate. Only capitalize at the beginning of a sentence.|
|email address||noun||Never replace this with "email ID" or "mail ID."|
|filename||noun||One word, no hyphens.|
|field||noun||This refers to form fields. Do not use "box" or "input."|
|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.|
|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."|
|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.|
|online||Only capitalize if this begins a sentence.|
|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.|
|run time||noun||Two words, no hyphen.|
|SSH||noun, verb||Always capitalize.|
|Summary, tl;dr||When writing for a non-US audience, always use "Summary."|
|up time||noun||Two words, no hyphen.|
|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.|
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.
|ACPI||Advanced Configuration and Power Interface Specification|
|AHCI||Advanced Host Controller Interface|
|CCID||Integrated Circuit Card Interface Device|
|CPLD||Complex Programmable Logic Device|
|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|
|IPMI||Intelligent Platform Monitoring Interface|
|JPC||Joyent Public Cloud, a deprecated term for Triton|
|LLDP||Link Layer Discovery Protocol|
|LLDP||Link Layer Discovery Protocol|
|LOM||Lights Out Management|
|MSI-X||Extended Message Signaled Interrupts|
|NIC||Network Interface Card|
|NVMe||Non-volatile Memory Express|
|OEM||Original Equipment Manufacturer|
|PCH||Platform Controller Hub|
|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|
|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|
|UFM||Upgradable Firmware Module|
|USB||Universal Serial Bus|
These are the rules for writing dates within content:
- For the full date: December 31, 1999, not Dec. 31, 1999, or 31 December 1999
- Do not use ordinals for the date: May 15 not May 15th
- No comma is used if the day is not specified (for example, December 1999)
- Always spell out the months and days of the weeks (January not Jan)
- Decades and centuries: 20th century, 1990s (no apostrophe), the '90s
When a variable is in place in our documentation, best practice is to name the variable with angle brackets:
>. Here are some common variables for code examples:
<container>(for container name or UUID)
Alternatively, some variables may appear with the dollar sign, such as
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:
- Find what they need
- Understand what they find
- Use what they find to meet their needs
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.
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.
|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|
Use one space after punctuation (periods, question marks, and colons). Do not use two spaces.
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.
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.
Sentence case is used for all headings. Capitalize the first word and proper nouns, nothing else.
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.
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.
Do not include leading or trailing punctuation in links with the exception of:
- Possessive apostrophes, such as
[this book is the Jones'](#)
- Quotation marks if the other quote mark is within the link context, such as an article including quotation marks like ‘Where Does Cloud Storage Really Reside? And Is It Secure?’
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 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.
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.
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."
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:
- Can you quickly scan this document to understand what information is being presented?
- If a user cannot see the colors, images, or videos, is the message still clear?
- Is the markup clean?
- Does this work well on devices with accessibility features?
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.
- W3C accessibility guide
- MailChimp's accessibility guide
- The accessibility cheatsheet on bitsofcode by Ire Aderinokun
- Accessibility evaluation for web writers on 4syllables
- 18F Accessibility Guide
Copyright notice for our works is not required but is recommended to ensure protection against innocent infringement.
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:
- The purpose and character of the use, including whether such use is of a commercial nature or is for nonprofit educational purposes
- The nature of the copyrighted work
- The amount and substantiality of the portion used in relation to the copyrighted work as a whole
- The effect of the use upon the potential market for or value of the copyrighted work
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.