Thank you for your interest in contributing to the Platform.sh docs! It's nice to share the goal of having clear and up-to-date documentation.
This content style guide should help make sure the Platform.sh docs are clear and consistent. It's intended for use by all contributors, from Platform.sh engineers to people from the community.
- About the audience
- Style defaults
- Address the reader directly
- Use inclusive language
- Format screenshots for sustainability
- Use the present tense
- Use contractions
- Explain abbreviations
- Use notes appropriately
- Add short descriptions
- Guidance enforcement
The goal of Platform.sh's documentation is to help tech-savvy users self-educate on how to use and get the most out of Platform.sh. Readers are generally familiar with common web development tools and practices (such as Git, branching, web servers, and databases), but not necessarily with server administration. Make sure to provide enough context, potentially by linking to existing resources elsewhere.
This style guide doesn't aim to cover every possible situation. If you come across something not addressed here, look for guidance in the Google developer documentation style guide. For a quick summary of that guide, see the Google style guide highlights.
Platform.sh docs should be in standard U.S. spelling, with reference to the Merriam-Webster dictionary.
The name of the company is always written as "Platform.sh", not only "Platform". It shouldn't be used as a link.
In keeping with the Platform.sh value that to "tell it like it is", focus texts on readers and talk to them directly.
This means using the second person ("you") and telling them what to do. Unless you have a very good reason (such as an action that has to be done by Platform.sh manually), avoid the first person ("we", "us", and "our").
| Use | Avoid |
|---|---|
| Next, download the template | Next, let's download the template |
| To get started quickly, use the default settings | We recommend that you use the default settings to get started quickly |
| Once you add the file to your repository | Once we've added the file to our repository |
Part of this directness is also avoiding using please.
Only use please if you're asking for something that benefits Platform.sh
or inconveniences the reader.
So it's OK in phrases like If you get an error, please open a support ticket.
In keeping with the Platform.sh value of being diverse, use language that welcomes everyone and excludes no one.
| Use | Avoid |
|---|---|
| After you invite someone, they can access your project | After you invite someone, he can access your project |
If they have the plans permission, they can add a plan |
If he/she has the plans permission, he/she can add a plan |
| denylist | blacklist |
| allowlist | whitelist |
Some guides to helping you make sure your writing is inclusive and accessible to everyone.
- Mailchimp guide to writing for accessibility
- Microsoft's ideas on writing for all abilities
- Google suggestions for writing accessible documentation
- Microsoft accessibility guidelines
- The Conscious Style Guide
To make your content as accessible as possible, the purpose of a link should be clear from its text alone.
Avoid links with text like click here
and instead try to include meaning inside the link itself.
Remember to use the proper format for links
The supporting documentation for the Web Content Accessibility Guidelines offers an explanation of why link purpose in the text alone is good.
| Use | Avoid |
|---|---|
| Read more information about images | For more info on images, click here |
When adding images and other visual elements to the docs, make sure the same content is available to those who can't see the content. This includes people who don't see and people who have images off in their browser for whatever reason.
Use alternative text for images that add content to a page that isn't otherwise there. Imagine what you would write if you couldn't include the image.
In situations where the image is for decoration or repeats text that's already present, use blank alternative text to show that.
See the proper format for images.
When taking screenshots of the console or other UI, focus only on the relevant part. Crop the screenshot so it only shows what users need to get the context. This helps keep the images fresh if other parts of the UI change.
Use your browser's developer tools to ensure your name and any other project-specific data isn't included.
Name the file descriptively so that it relates to what's being shown.
Readers are often using the documentation they're reading at that moment. Even if they might be using the code in the future, writing about the present is clearer and more direct.
Use the present tense to describe actions unless the action will be at a specific time in the future (you will get an email on October 17).
| Use | Avoid |
|---|---|
| After the site deploys, you see a welcome page. | After the site deploys, you will see a welcome page. |
| The details of the process vary from project to project. | The details of the process will vary from project to project. |
| Once you save your build environment variable, your environment is redeployed | Once you save your build environment variable, your environment will be redeployed. |
To keep this documentation welcoming and make it easier to scan,
feel free to use contractions that are common in speech.
Apply this even to negative contractions
as there is some evidence people are less likely to skip the negative in don't than in do not.
Avoid contractions that are uncommon or that might be confusing
(such as making readings think something is a possessive rather than a verb).
Make use to use it's only for a contraction of it is, not as a possessive.
| Use | Avoid |
|---|---|
| Don't hesitate to use contractions. | Do not hesitate to use contractions. |
| The environment is ready. | The environment's ready. |
| This command returns what its name is. | This command returns what it's name is. |
Too many abbreviations can be confusing to readers. Make sure to explain any abbreviations that might be unfamiliar the first time they're used.
Avoid abbreviations for Latin terms, such as i.e., e.g., and etc..
as these aren't always understood correctly.
| Use | Avoid |
|---|---|
| It's a new key management service (KMS). You should use this KMS carefully. | It's a new KMS. You should use this KMS carefully. |
| You have many service options, including Elasticsearch and Kafka. | You have many service options, e.g. Elasticsearch, Kafka, etc. |
Notes are pieces of information that stand outside the normal text flow. Use them for short ideas that aren't. Don't use too many in one place or they lose their value.
There are three types of notes:
- Note: For neutral information that's worth taking into consideration.
- Info: For helpful information that might save the reader time or otherwise benefit them.
- Warning: For information that's serious and must be taken into account. Ignoring a warning could cause things to break or data to disappear.
Each type of note has its type as the default title. You can override the title to anything, but keep it short.
See how to format notes.
Each page should ideally have a description that can be reused in other places.
description is of the options in the front matter.
It allows you to set a meta tag for search optimization
and text to appear on listing pages.
Add a description of what the page contains, something that makes sense out of the context of the rest of the page.
Remember to keep it short. If possible, it should be no more than about 160 characters.
Some of the rules are enforced with Vale, a linter for prose.
Because writing style is subjective and no checking tool is perfect, the rules are mostly set to warnings rather than errors. So checks note when something might be wrong, but use your common sense and ignore them when appropriate.
One exception is spelling, which returns errors.
If there's a word that's been falsely flagged as a misspelling,
add it to the list in styles/Vocab/Platform/accept.txt.
Another exception is words like simply, which can come off as condescending.
For more, see an article on words to avoid
or a video on not saying 'simply'.
To get the most out of the rules, install Vale
and run it locally with the command lint-prose from the repository root.
Or use it in your IDE, such as with Vale for VS Code.
All pull requests against the default branch are also checked by Vale automatically.