Skip to content

Style manual

Language & Wording#

  • Public documentation is in US English (Sorry! We have to standardize and your friendly documentation writer is US-based).
  • Client documentation is geared towards the client language.
  • When using an acronym or technical term for the first time, define it where possible (“Red Hat Enterprise Linux (RHEL) is a Linux distribution developed by Red Hat and targeted toward the commercial market.”)
  • Link to products and applications when introducing them, or add a footnote.
  • If a technical term requires a longer definition that would break up the flow of the document, add a footnote, or put it in a glossary or appendix at the bottom of the document and reference it. (“See Appendix A for an explanation of multi-tenancy.”)

Punctuation & Grammar#

  • amazee.io - no capitalization, always with the dot.
  • Lagoon - capitalize it!
  • Multi-word descriptors are hyphenated. (Open-source software, multi-tenant application.)
  • If you’re unsure if something should be hyphenated, one word, or two words, please look it up! We use a lot of tricky words but there are a lot of good resources out there.
    • Here is the search result for “rollback” or “roll back” which informed me that the following was correct: “This will make it easier to roll back in case of an issue with the rollout.” There was also an entry indicating “rollback” is not incorrect, but not the common usage yet. Go with the most proper/most common usage when in doubt.
    • Crontab is one word.
    • “Cron job” is two words.
    • CircleCI is one word, Travis CI is two words.
    • AP Style uses “email” and not “e-mail,” so we’ll go with “email.”
    • Backport is one word.
    • Be aware of words that are one word as a noun/adjective but two words as a verb:
      • “Set up your computer” vs “ The setup was difficult.”
      • “Log in to the site” vs “I can’t remember the login information.”
      • “It’s not hard to roll out updates” vs “We had a great rollout.”
      • “We can roll back the database” vs “We had to do a rollback.”
      • “Check out the file” vs “The checkout process.”
    • Avoid abbreviations (Use kubernetes, not k8s).
      • When referring to Node.js, avoid calling it “Node.” Be consistent in calling it “Node.js.” We use the term “node” throughout our documentation and want to avoid potential confusion.
      • Use the oxford comma. Example: “This can be to inject an additional environment variable, change a service configuration, or even install additional tools.”
      • In general, word and punctuate documentation to read as you would read it aloud. Short, easy-to-read sentences, more commas. We want people to pause and digest the information, and not have trouble parsing the sentences.
    • Try to keep from splitting phrases and infinitives in your sentences. This is for readability, not correctness. Example: “Given the environment variables, this will build and tag the images for publication.” instead of “This will, given the environment variables, build and tag the images for publication.”
  • Acronyms are capitalized. (PHP, SSH, API)
    • The exception to this is when the acronym is referring to a service that is in lowercase and to capitalize it would be confusing. In this case, the acronym is often put in code bracketing. (“The cli container, “connect to the php container.”
  • Only proper nouns are capitalized.
  • There are some exceptions, when, for instance, a service capitalizes something within its documentation. (“Lagoon needs a Service Account within OpenShift (read more about Service Accounts).”)
    • Do capitalize:
    • Drupal, Lagoon, Git, NGINX
    • Do not capitalize:
    • cluster, pod, container

Camel-casing#

Be aware of which nouns use camel-casing. This can be really confusing, so don’t assume!

✅ Use camel-casing:

  • ClamAV
  • GitBook
  • GitHub
  • GitLab
  • GraphQL
  • MariaDB
  • MiniShift
  • MkDocs
  • MySQL
  • OAuth
  • OpenSearch
  • OpenShift
  • PhpStorm
  • PHPUnit
  • PostgreSql
  • RabbitMQ
  • Rocket.Chat (note the period!)
  • SilverStripe
  • StatusCake
  • WordPress
  • VirtualBox

🚫 Do not use camel-casing:

  • Bitbucket
  • Blackfire
  • Cloudflare
  • Elasticsearch
  • Docker Hub (two words!)
  • Fluentd
  • Golang
  • Homebrew
  • Keycloak
  • Logstash
  • Markdown
  • Statuspage
  • Xdebug

Look up the standard way of referring to products and tools, and use that. Be consistent! - Example: Node.js is correct. Do not call it “Node” or “NodeJS.” or “node.js.” - NGINX is all caps - Git is capitalized - npm is all lowercase.

File names and endings * YAML files should end in .yml when writing about them, not .yaml. * Wrap file names in code formatting or a mono-spaced font. (composer.json, docker-composer.yml).

Headings#

  • Use semantic headings (h1, h2, h3) properly.
  • Use sentence case for headings.

Resources#