Capitalization
As a general rule, capitalize words and terms that are proper nouns or would normally be capitalized. If you're uncertain, default to not capitalizing terms.
For Octopus, this means capitalizing product names, tool names, and the names of features, but not general concepts.
The following are capitalized when they refer to the product or product names:
- Octopus Server
- Octopus Cloud
- Spaces
- Tentacles
- Octopus Runbooks (the feature)
The following are not capitalized (unless at the start of a sentence):
- deployment target
- environment
- server
- built-in repository
- runbooks (the concept, not the feature)
- agent
- workers
Proper nouns vs common nouns
A proper noun is the name of a specific instance of a thing, such as Australia and Octopus Deploy. A common noun is a general concept that refers to a class of things, such as country and deployment tool.
The context in which we use a word determines whether it's a common or proper noun. For example:
With the Octopus Spaces feature, you can create separate spaces for each of your teams' infrastructure and projects.
In the above example, Octopus Spaces is the name of the feature, so it's capitalized, however, separate spaces refers to spaces as a general class of things and is not capitalized.
As another example, we capitalize Platform Engineering when we mention it as a concept, but not when we refer to platform engineers as a group, just like we don’t capitalize other job titles when they’re mentioned as a group. However, we do capitalize when we use a specific person’s job title. For example:
Platform Engineering aims to create an environment where developers can focus more on writing code and less on managing infrastructure. Your platform engineers will work closely with your application engineers to understand their needs. As Ping Chen, Lead Platform Engineer at Financia, explains, “I support our application teams by providing patterns and practices for their deployment pipelines.”
Special note for IDs
There are a lot of IDs in the codebase. When referencing parameters in the code, match the casing in the codebase, i.e., ServerId, but when discussing the Server ID in the text, capitalize ID. (Id is a psychological term, ID is short for identification).
Match the UI
The only exception to the proper noun versus common noun rule is to use the same style as the UI you're documenting.
For instance, deployment target isn't a proper noun, so we wouldn't normally capitalize it. However, if you're instructing a user to click a UI element in the Octopus web portal and the UI label is capitalized or all caps, you should mirror the style from the UI.
Titles/headings
We write titles in sentence case and only capitalize words that are normally capitalized.
For example, Kubernetes and Git are normally capitalized, so they're capitalized in this heading: Sourcing Kubernetes manifests from Git
But in this example, we only capitalize the first word: Choosing a container platform
The Oxford comma
Use the Oxford comma - a comma after the penultimate item in a list of 3 or more items, before and or or.
For example, on-premises, cloud, and serverless.
Single spaces after full stops
Although it's a habit for some, please try to avoid double spaces after full stops. We use single spaces.
How we write common Octopus words
- API key (lowercase k)
- back-end (use a hyphen, don’t write as 2 words or one)
- blue/green deployments (use a forward slash, don't write blue-green)
- cloud (no capitalization unless it’s the name of a product)
- cloud-native (use a hyphen, and note this is the only instance where we use the word native)
- codebase (one word)
- command-line (use a hyphen, don’t write as 2 words or one)
- Configuration as Code, or Config as Code (not CaC)
- Continuous Delivery (capitalize the C and D)
- Continuous Deployment (capitalize the C and D)
- Continuous Integration (capitalize the C and I)
- day-0, day-1, day-2 (don't capitalize the d, use a hyphen between day and the number)
- enterprise (lowercase e, unless we're talking specifically about our Enterprise tier)
- Happy deployments! (no capitalization for deployments, use an exclamation mark at the end)
- in-the-box (use hyphens)
- JBoss (capital J and B, one word)
- Kubernetes agent (lowercase a for agent, unless you're referencing labels in the Octopus UI)
- on-premises (use a hyphen, don’t shorten to on-prem, must have an s on the end or else it has a completely different meaning)
- open source (no hyphen unless it's a compound adjective. For example, If your software's open source, you must maintain it is correct without the hyphen. Octopus contributes to the developer community with open-source projects is correct with the hyphen.)
- out-of-the-box (use hyphens)
- Platform Engineering (capitalize the P and E when referring to Platform Engineering as a concept - see rules above on proper versus common nouns for further nuance)
- PowerShell (capital P and S)
- proof of concept (no capitalization or hyphens)
- Redeploy (not re-deploy)
- Rerun (not re-run)
- Tentacle, Polling Tentacle, and Listening Tentacle (always capitalize)
- virtual machines (no capitalization when writing in full, but abbreviate to VMs)
- worker, worker machine, default worker pool, built-in worker (don't capitalize – this is a change as of May 2024)
Note that SQL is pronounced “sequel”. Knowing this helps you use the correct article. For example, a SQL database is correct, an SQL database is incorrect.
When in doubt about how to write something, we generally follow Wikipedia's conventions.
Talking about our pricing plans, instances, and licenses
- tier is how we refer to the plans we offer customers on the pricing page. For example, we might say, You're on the Free tier or You're on the Professional tier.
- We don’t capitalize the word tier, but we do capitalize the name of the tier, i.e., Enterprise, Professional, Free.
- instance is how we refer to a customer's unique version of Octopus software. For example, we might say, Your Octopus Cloud instance is now ready to use.
-
license is the number/key that identifies a customer’s unique Octopus instance.
When we're specifying between Cloud and Server for our tiers, we write: - Octopus Cloud Enterprise tier or Octopus Server Enterprise tier
- Octopus Cloud Professional tier or Octopus Server Professional tier
- Octopus Cloud Free tier or Octopus Server Free tier
Words to avoid (and what to use instead)
- Allows (lets)
- Article (post)
- Enable (let)
- Hack up (create)
- Leverage (use)
- Once (after)
- Usage (use)
- Utilize (use)
- Whilst (while)
- Within (in)
Try to use inclusive and gender-neutral language. There are common software terms that are offensive that you should replace with non-offensive alternatives. Examples include:
- White list (safe list/allow list)
- Black list (exclude/block list)
- Gray list (provisional)
- First-class (core feature/built-in)
- Native (built-in)
- Disable (deactivate)
Refer to Google’s word list and their documentation on inclusive writing for the full list.
We also avoid using exclamation marks, as they lose their impact and can look unprofessional. Other than using one with Happy deployments! we use them sparingly. Default to not using them.
Writing the possessive of Octopus
- The possessive of Octopus is usually written as Octopus’s.
- If you say the s twice, use apostrophe s, otherwise just the apostrophe.
- If you’re unsure, just write Octopus Deploy’s.
Writing bulleted or numbered lists
- Start with a capital letter.
- If the list only contains fragments, don't punctuate.
- Punctuate full sentences only.
- Be consistent in each list (for example, use full sentences with punctuation for all points, or use fragments without punctuation for all points).
- Ensure each point flows on from the lead-in as a proper sentence if you’re using fragments.
Numbers
You should spell out zero and one, so people don’t confuse them with the letter O and a lowercase L which can look like this:l. This is especially important for accessibility.
Numbers 2 and above should use the numeral unless it’s the start of a sentence. For example: Ten new employees started on Monday, and 12 start next week.
Ordinals should use the numeral unless it’s the start of a sentence or an expression.
- Penelope won 1st place in the egg and spoon race.
- I gave them my first impression of the third-party integration.
For use cases not mentioned here, refer to Choosing numerals or words from the Australian Government Style Manual.
Dates
Generally, spell out the day of the week and the month. Abbreviate if space is an issue.
Write dates in the US format: day, month, date, year.
Example: Thursday, September 29, 2022.
Time
Here are some examples of how we write time:
- 12pm PT
- 3am ET
- 12:30pm UTC
- 3:30am AEST