Sumo Docs Style Guide
This page describes how to author Sumo Docs, which are written in GitHub-flavored markdown.
The Sumo Logic Style Guide is a guide to language at Sumo Logic, so that we can speak as one company with a unified voice, and know what we mean when we talk about our product. The Style Guide began as a document used by the Documentation team to make decisions about tone, voice, and word usage. We thought it would be useful to share with everyone in our community.
This is a living document. If you're looking for a style rule or UI component usage that's not defined here, let us know. The Documentation team will look it up and add usage guidance.
Writing resources
If you need help with a convention, word to use, or format to follow, we will keep a cheatsheet of styles here. We also follow:
For terminology usage guidance, see our Word List.
If you're new to writing tech content or would like to learn more, check out these resources:
- Write the Docs. Association of tech writers, developers, trainers, and more that have collected ideas, created training and guidelines, and actively discuss documentation.
- Google Technical Writing Courses. Self-paced courses to refine your writing. The courses may use a style different from ours, but still an excellent way to get started.
- Every Page is Page One. A helpful method for considering what goes into a page is to think of every page as page one. With the extreme use of search engines or sharing a link to find content, users may land in the middle of a section or tutorial. These ideas help hone your content and focus on user needs.
Helpful blogs on tech writing:
- Writing for the Web. Guidance on writing for the web, including insights on technical writing and learning.
- Feathers. Blog for technical and fiction writing.
- I'd rather be writing. Guides and thoughts on tech writing process and content.
The Documentation team will review submissions, provide suggested edits, add new content into the navigation, and answer any questions you have.
To create a new doc quickly, use a template. You can copy and paste the file, add your content, and submit a PR.
Voice and tone
- Clarity and professionalism. We are clear, genuine, and trustworthy. We understand that our customers entrust us with their vital data and never make light about our commitment to data access and security.
- Engagement and assistance. The reader should feel confident and informed. We should strive to engage our customers and show them where to get additional assistance when needed.
- Professional description. Describe Sumo Logic in a professional and truthful manner. Avoid generic, unsubstantial adjectives like "very" or phrases like "we're the best". Instead, illustrate these points by letting our product speak for itself.
- Conversational tone. Avoid using a stiff, institutional voice. Instead, write with an instructive and conversational tone, using the sort of words that you would use in a face-to-face conversation. For example, when linking to the support site, use terms like "Need help? Let us know" instead of "Please email our support personnel" to give our company a friendly face.
- Reader address. Address the reader as "you", as you would in conversation. For example, instead of saying, "The user must provide his or her API key" or "One must provide their API key", say, "You'll need to provide your API key".
- Readability and SEO. Instructional content and blog posts should be written at approximately the 8th-grade reading level, particularly in introductory sections, for readability and SEO. You can test your content here.
- Brand guidelines. Our brand guideline is to always refer to “Sumo Logic”, rather than Sumo. To be more conversational, it is also fine to say “we”.
- Gentle Language. Use “need to” instead of “have to” or “must”. “Have to” and “must” can sound harsh and unfriendly.
- Judicious use of absolutes. Be judicious in use of “always” and “never”. Sometimes it’s appropriate to say “always” or “never”. Keep in mind though that “always” can imply a result that is not guaranteed, and “never” may very well not be the case — the exception makes the rule.
- Error messaging. When explaining a process or procedure, clarity is critical. Edit words that distract or confuse. Put yourself into the reader's shoes and think about what actions you recommend to them when an error message is displayed, rather than merely stating what went wrong. Example: "Could not create the user." vs "This email is already registered in the system. Please use a different email or contact Sumo Logic for assistance."
- Humor. We have a sense of humor! Conveying that we do serious work, but we do not take ourselves too seriously, makes Sumo Logic feel likable.
Active voice
When writing instructions, use the active voice whenever possible. This example below gives a call to action for the reader or user to effectively get something done. It also reduces word count and keeps instructions clear.
General statements
✅ Do | ❌ Don't |
---|---|
Sumo Logic ingests multiple streams of data. | Multiple streams of data are ingested by Sumo Logic. |
Task directives
We need them to complete a task. No need for please.
✅ Do | ❌ Don't |
---|---|
Build the query using the following... | Please build the query using the following... |
Instruction introduction (stem)
Introduce your instructions with the goal, then dive into the instructions. This is called a stem, and it helps focus the task and keeps you active:
✅ Do | ❌ Don't |
---|---|
To add a new collector: 1. Access Sumo Logic and find the... | When you need to add a new collector, access Sumo Logic and find the... |
Inclusive language
By writing inclusively and using culturally neutral language, our words resonate with global audiences and make everyone feel welcome, no matter their race, gender, socioeconomic status, and ability.
Avoid Regional Language
- Do not use idioms, slang, expressions, or terminology only understood by a specific region or group.
Simplify Language
- Avoid overly technical jargon.
- Don’t use words just because they sound better. Choose short, simple words over long and complicated ones.
Gender Neutrality
- Unless you're referring to a specific person, do not use gender pronouns (he/she).
Cultural Neutrality
- Use culturally neutral terms to replace terms with negative connotations. For example:
✅ Do | ❌ Don't |
---|---|
"allowlist" "denylist" "placeholder data" "primary" or "main" "press" or "click" | "whitelist" "blacklist" "dummy data" "master" "hit" |
Doc structure summary
- Frontmatter. Metadata formatted in YAML that goes at the top.
- Introduction. Tell the user in the doc introduction (first paragraph) what the page teaches, why they should read it, and who should read it.
- Contextual guidance. Let the user know what step/place they are in for a tutorial in the introduction/at top. The layout automatically provides a previous/next at the bottom of the page.
- Linking. Link out to important concepts and overviews for additional reading. This is helpful for instruction pages or tutorials.
- Conciseness. Keep instructions concise, easy to follow, and with not too many screenshots.
- Admonitions. Include any notes, warnings, tips, or other admonitions.
Abbreviations
Avoid the use of abbreviations like “e.g.”, “i.e.”, and “etc.”. Although they may be well understood, such abbreviations don’t support our goal of a conversational tone. In other words, don’t use language you wouldn’t use verbally.
✅ Do | ❌ Don't |
---|---|
for example | e.g. |
✅ Do | ❌ Don't |
---|---|
that is | i.e. |
Acronyms
An acronym uses the first initials of a word or phrase, for brevity. Our industry is full of them, and they can get confusing if their usage isn't clear. Acronyms should be capitalized, if not used directly in a query. Unless the usage is clear from the context, for the first usage, spell out the phrase, then present the acronym in parenthesis. For example: Secure Shell (SSH).
All companies have numerous acronyms for products, features, solutions, and more. Our documentation includes acronyms for Sumo Logic and third-party software. Always fully spell out the first instance of the acronym on the page, then you can use it throughout. Do not spell out in a heading, but in paragraphs or bullets.
For example, the first time you use AWS Application Load Balancer (ALB), you introduce or use it like that the first time on the page. Through the rest of the page, you can use ALB.
Admonitions
We refer to callout elements like Tip, Note, Warning, and Caution as admonitions.
Docusaurus has a special syntax to create admonitions and callouts, including note, tip, important, caution, warning, and sumo. You can use markdown content in the admonitions, code blocks, links, bullets, images, videos, and much more.
- Markdown
- Result
:::note
This is a note.
:::
:::tip
This is a tip about a cool feature option.
:::
:::important
This is some vital information.
:::
:::warning
This could note important and problematic information.
:::
:::danger
This action is dangerous and could result in data loss.
:::
:::sumo[Best Practice]
Highlight specific info, best practices, links, [training links](https://www.sumologic.com/learn/training/), and other information from Sumo specialists. You can change the title based on the content.
:::
This is a note.
This is a tip about a cool feature option.
This is some vital information.
This could note important and problematic information.
This action is dangerous and could result in data loss.
Highlight specific info, best practices, links, training links, and other information from Sumo specialists. You can change the title based on the content.
You can use code blocks in admonitions. Here's an example:
Here's a cool tip.
"overrides": [
{
"series": [],
"queries": [
"A"
],
"userProvidedChartType": false,
"properties": {
"type": "column"
},
"unsafeCanvasJSProperties": {
"bevelEnabled": true,
"indexLabelPlacement": "inside",
"indexLabel": "{y}",
"indexLabelOrientation": "vertical"
}
}
]
Beta releases
Closed beta
Closed beta release features are exclusively available to participating customers. Documentation for these features is not publicly accessible; Sumo Logic representatives provide the documentation links only to the involved customers. These links are excluded from our table of contents.
To format a closed beta release:
- Underneath the frontmatter, add:
- The Robots meta tag, which prevents search crawlers from picking it up.
- The Sumo Logic Docs beta label.
---
id: xyz-source
title: XYZ Source (Beta)
description: The XYZ Source provides a secure endpoint to receive event data.
---
<head>
<meta name="robots" content="noindex" />
</head>
<p><a href="/docs/beta"><span className="beta">Beta</span></a></p>
First paragraph goes here...
- Publish the document.
Open beta
When the feature moves to open beta, it becomes available to all customers. Help topics for an open beta feature have a beta label at the top, appear in the site table of contents, and are linked from the Beta Features section.
To format an open beta release:
- Underneath the frontmatter, add the beta label.
---
id: xyz-source
title: XYZ Source (Beta)
description: The XYZ Source provides a secure endpoint to receive event data.
---
<p><a href="/docs/beta"><span className="beta">Beta</span></a></p>
First paragraph goes here... - Add the doc file path to
sidebars.ts
under its appropriate section, then add to the beta section with the same file path. For example, if your doc path isdocs/get-started/sumo-logic-ui.md
, add it to theget-started/
section, then add to thebeta/
section with the same file path.sidebars.tsgetstarted: [
{
type: 'category',
label: 'Welcome to Sumo Logic',
items: [
'get-started/sumo-logic-ui',
...
beta: [
{
type: 'category',
label: 'Beta',
items: [
'get-started/sumo-logic-ui',
... - Publish the doc.
When the feature goes GA, remove the beta label and remove a description of the feature from the /docs/beta
section.
Capitalization
- Title case (initial cap) all doc titles. Example:
Global Intelligence for Apache Tomcat App
- Sentence case all other headers (H2, H3, H4). The only exception is proper nouns, which are always title case. Example:
Throughput signals and contributing factors
Code (inline)
Use single backticks (` `) to format inline code as monospace font. Example use cases include commands, operators, API method names, and error messages. For information on code blocks (scripts), see Code Blocks.
- Markdown
- Result
`_view = sumologic_slo_output`
_view = sumologic_slo_output
Code (blocks)
Use code blocks to format scripts, such as the JSON example below. This is important for scripts and CLI. Format blocks of code by placing triple backticks before and after the code.
Code blocks are intended only for code snippets that users can copy, paste, and run in their own terminal. Do not use code block formatting for error messages (see Code (Inline)), as this isn't something you'd run in a terminal.
If you know the code language, include that in the first set of backticks to activate syntax highlighting. See this list of supported languages. Use sql
to format Sumo queries and json
for Sumo logs.
- Markdown
- Result
{
"employee": {
"name": "Jane Smith",
"team": "Operations",
"manager": true
}
}
Here's how to add a title to your code block.
- Markdown
- Result
function HelloDocusaurus() {
return (
<h1>Hello, Docusaurus!</h1>
)
}
To highlight lines in the code, use {#}
in the title line with lines numbers. This example highlights lines 2 through 6.
- Markdown
- Result
_sourceCategory=reinvent/travel/checkout
[subquery:_sourceCategory=reinvent/travel/nginx
| count by src_ip
| topk(1,_count)
| compose src_ip keywords
]
| json field=_raw "funcName"
| where funcname in ("process_cart","charge")
| if (funcname = "process_cart" , "Checkout", "Purchased") as funcname
| count by funcname
For a full list of options, see Docusaurus Code Blocks.
Collapsible text blocks
Use the Docusaurus Details feature to collapse long, additional content and long code samples. When collapsed, the content can be searched, but not displayed, when loading a page. Place long lists or lots of content in this section. The reader can expand/collapse as needed. Important content like required steps and instructions should not be placed in an expander.
You can include markdown content in expanders including code samples, embedded videos, bulleted lists, and more.
Add a title for the expander between the <summary>
tags. Then, add all content after <summary>
tags and before the closing <details>
tags.
- Markdown
- Result
Toggle me
"overrides": [
{
"series": [],
"queries": [
"A"
],
"userProvidedChartType": false,
"properties": {
"type": "column"
},
"unsafeCanvasJSProperties": {
"bevelEnabled": true,
"indexLabelPlacement": "inside",
"indexLabel": "{y}",
"indexLabelOrientation": "vertical"
}
}
]
Contractions
Using contractions contributes to our goals of striking a conversational, friendly tone.
It's okay to use common contractions like “I'm”, “they're”, and “you’ll”. Spell out all negative contractions (for example: use "cannot", not "cannot"), as they can be easily mistaken for the opposite meaning.
Avoid less common contractions, like “should’ve”, or “it’ll”.