Style Guide
Welcome to the JupiterOne writing style guide 👋
From components to grammar, these guidelines will cover all you need to know to make meaningful contributions to our documentation here at JupiterOne. 😊
If you've found this by mistake, welcome! This is an INTERNAL resource! Only JupiterOne employees may contribute to our documentation... for now... 🙈
Purpose​
Through our documentation, we at JupiterOne seek to enable users and/or evaluators to gain a deeper understanding of our product and its technical capabilities–allowing them to get the most out of our product.
Our documentation values​
- Accurate: Features up-to-date information and showcases what is possible.
- Accessible: Provides entry points to various levels of technical experience.
- Open: Structured in such a way that provides contribution from across the organization.
- Flexible: Able to accommodate a variety of content types at scale.
JupiterOne tone and voice​
When writing for our documentation, we always need to be conscious of how we communicate, and that is where voice and tone come into play. They both govern the way in which we communicate and inform the composition of messaging and other content. Let's break down both tone and voice, and how they relate to our production of technical content. So, what the heck is the difference? Great question! Just keep reading...
Voice​
JupiterOne's voice is derived from its character, by who we are and what we do. It shapes how we interact with the world and is driven by our purpose. Think of it as the lens through which all our content passes. It remains consistent. The thread running through everything we do, (from our product, design, documentation, support, etc.) is a genuine desire to empower our customers with a platform that strengthens their organization's security posture and streamlines their ability to visualize their cyber assets. We want to write in a manner that shows we are deeply knowledgeable about both the industry and our platform
Tone​
Tone, as opposed to voice, is a bit more nuanced. Our tone can (and does) change depending on who we speak to. You probably don't talk to your coworkers the same way you would talk to your pet. That'd be slightly... unsettling. When writing, we retain our overall voice, but we adapt our tone to the audience we're addressing when we write. Whether it's a board member, a client, a user who needs help with a technical issue, or a developer seeking reference material, we match our tone to the context of the situation.
Grammar and usage​
Now that we've covered the lenses of voice and tone, let's get into the grammar and syntax decisions we've made to keep our content stylistically cohesive across the writing. This is more around the semantics and shaping of our content, fun!
JupiterOne Word Usage​
Always write out JupiterOne and do not use the abbreviation "J1".
Capitalization​
It's common nouns versus proper nouns. We, of course, capitalize all the names of the J1 apps that appear in the top nav bar in the UI, such as Insights, Assets, Alerts, Query Builder, and Integrations, when we are referring to them as the official J1 apps. However, we do not capitalize common components of the J1 apps, such as rules, charts, widgets, assets, and alerts.
We capitalize the field names, page/screen titles, column headers.
Writing in second person​
Since we're not writing all this awesome content solely for ourselves, we need to be sure to address our readers and the audience when we are creating content for the documentation space. This form of writing will probably already be familiar to you, as most technical content speaks directly with its reader. This can either be explicit or implicit.
E.g., 'To add this integration, you need to configure an API token...' vs. 'To add this integration, (you need to) configure an API token...'
In the first example, we explicitly refer to the reader and address them directly, while in the second example it is implied. Using the implied method is helpful in applications such as user flows, where repeating the explicit you will get extremely redundant.
Passive vs. active writing​
A controversial topic these days. Active writing is typically touted as the soup de jour, and passive writing has seen less enthusiasm as of late. BUT, as with everything, there's a bit more nuance to the topic that just "Active good, passive bad". It really depends on what you, the writer are trying to convey and how you go about doing so.
When writing content, if you want to emphasize the subject (who/what is doing the action), active voice is what you're after. Passive voice is best suited for highlighting the recipient or outcome of the action.
Example​
- Passive: Your account has been successfully created.
- Active: You successfully created your account.
In the above example, the passive voice is putting emphasis on the account, while the active voice is putting emphasis on the user who created their account. Knowing these differences is particularly useful when drafting copy for scenarios where want to emphasize the outcome of the action with a passive voice rather than emphasize the subject who is doing the action.
When writing about what users can do with our platform or a feature, it is best to use active voice (e.g., "You can create a query with JupiterOne's Query Builder by navigating to..." as opposed to "Queries can be created with JupiterOne's Query builder...").
More examples​
- Passive: Your password has been reset.
- Active: You have reset your password.
Admonitions​
These are a pretty nifty tool that come built in with Docusaurus, and we leverage them to callout important information that needs to be emphasized to a reader for one reason or another. (You might have noticed the tip admonition at the beginning of page!)
We currently use three different admonitions for various purposes:
This is an info admonition. We typically use these to point a user to additional resources relating to a topic they might navigate to, to learn more.
This is a note admonition. These are used for calling out something important that might be a caveat or bit of information that will help the user understand a topic by providing more context.
This is the danger zone admonition. Meant only to warn a user of some impending doom. For example, warning a user that if they complete a certain action, it will have consequences they might not fully be aware of (e.g., situations where data loss may be a result of their action).
Admonitions are formatted within a .md or .mdx file as so:
:::{admonition-type} (info | note | warning)
Here is the admonition message.
:::
Boldface and user paths​
When writing out steps for a user to follow in order to accomplish a task, we want to utilize boldface to indicate the UI for which the user is actually interfacing—meaning we do not boldface areas of the UI which are static and not interacted with, such as column headings. It is also best practice to utilize > when illustrating a flow that involves more than one navigation step. For instance: "From the JupiterOne dashboard, navigate to Alerts > Manage rules. Typically, we'd want to break down complex user paths into a couple of steps if the flow is greater than three clicks. E.g., Navigate to Settings > User > Profile > Select avatar is getting a bit lengthy.
We could instead split it into two steps using the first thee (Settings > User > Profile) in step one and the last part of the flow as a separate new line, especially since they will also need to actually perform the action of selecting their profile's avatar image. It would look something like this:
#### To change your profile avatar image:
1. Navigate to **Settings > User > Profile**
2. From your profile, click **Select avatar** and choose your desired avatar.
Punctuation​
- Oxford or serial comma: Use it here, here, and here.
- Em Dashes (—): If you use them, format them**—like this—**with NO spaces on either side. Do not use a hyphen (-), we don’t like hyphens.
- En Dashes (–): Use to denote a range of numbers, such as October 7–15. Do not use a hyphen (-). If you haven’t heard already, we don’t like hyphens.
- Hyphens (-): Use when linking words together. Example: ‘Product-specific shipping’ or ‘third-party solutions’.
- Contractions: Use them whenever they won’t sacrifice clarity. They make copy sound more conversational. (Help center and blog content: Yes; Documentation: No).
Other cool stuff​
Docusaurus provides a lot of useful features to leverage within our documentation. You can find more information about what is available via Docusaurus' docs. We'll also continue to build onto our style guide as our documentation product matures and we implement new features!