Skip to main content

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:

The Sumo Logic Docs team will review submissions, provide suggested edits, add new content into the navigation, and answer any questions you have.

tip

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

  • 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.
  • The reader should feel confident and informed. We should strive to engage our customers, and show them where to get additional assistance when needed.
  • 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.
  • Avoid using a stiff, institutional voice. Instead, write with an instructive and conversational tone. 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.
  • 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.
  • 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 are recommended 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."
  • 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. For example, "Sumo Logic ingests multiple streams of data", not "Multiple streams of data are ingested by Sumo Logic".

This gives a call to action for the reader or user to effectively get something done. It also reduces word count and keeps instructions clear.

Active ✅Not Active ❌Why?
Add a resource...You can add a resource...They know they can do a thing. Clearly state to do the thing.
Build the query using the following...Please build the query using the following...We need them to complete a task. No need for please.
To add a new collector:
1. Access Sumo Logic and find the...
1. When you need to add a new collector, access Sumo Logic and find the...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.

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.

  • Do not use idioms, slang, expressions, or terminology only understood by a specific region or group.
  • Avoid overly technical jargon.
  • 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".
  • Unless you're referring to a specific person, do not use gender pronouns (he/she).
  • Use culturally neutral terms to replace terms with negative connotations. For example:

✅ "allowlist"
✅ "denylist"
✅ "placeholder data"
✅ "primary" or "main"
✅ "press" or "click"

❌ "whitelist"
❌ "blacklist"
❌ "dummy data"
❌ "master"
❌ "hit"

Doc structure summary

  • Frontmatter (metadata) goes at the top.
  • Tell the user in the doc introduction (first paragraph) what the page teaches, why they should read it, and who should read it.
  • 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.
  • Link out to important concepts and overviews for additional reading. This is helpful for instruction pages or tutorials.
  • Keep instructions concise, easy to follow, and with not too many screenshots.
  • 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.

  • Instead of "e.g.", use “for example”
  • Instead of "i.e.", use “that is”

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.


:::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.
:::

You can use code blocks in admonitions. Here's an example:

tip

Here's a cool tip.

You can highlight lines in code blocks
"overrides": [
{
"series": [],
"queries": [
"A"
],
"userProvidedChartType": false,
"properties": {
"type": "column"
},
"unsafeCanvasJSProperties": {
"bevelEnabled": true,
"indexLabelPlacement": "inside",
"indexLabel": "{y}",
"indexLabelOrientation": "vertical"
}
}
]

Beta Releases

Closed Beta

A closed beta release is limited to customers participating in the beta. Help topics for a closed beta feature have a Beta label at the top, but do not appear in the site table of contents or Beta Features. Sumo Logic representatives provide links for closed beta topics only to customers participating in the closed beta. At the end of the beta period, we remove the Beta label and and publish the topics so they are available to everyone.

For a Closed Beta release:

  1. Underneath the frontmatter, add the Robots meta tag (to prevent search crawlers from picking it up) and the 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...
  1. Do not add the doc to sidebars.ts.
  2. Do not list the feature in Beta Features.
  3. Publish the doc.

When the feature moves from Beta to GA, remove the Robots meta tag, remove the Beta label, and add the doc to sidebars.ts.

Open Beta

An open beta release is 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 a description of the feature in Beta Features. At the end of the beta period, we remove the Beta label and remove the description of the feature from Beta Features.

For an Open Beta release:

  1. 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...
  1. Add the doc in sidebars.ts.
  2. List the feature in Beta Features.
  3. Publish the doc.

When the feature moves from Beta to GA, remove the Beta label and remove a description of the feature from Beta Features.

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.

Example: _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.

note

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.

{  
"employee": {
"name": "Jane Smith",
"team": "Operations",
"manager": true
}
}

Here's how to add a title to your code block.

src/components/HelloDocusaurus.js
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.

_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

You can use an expander to collapse long content that can be searched, but not displayed, when loading a page. We recommend using expanders only for additional content and long code samples. Content required for instructions and steps should not be placed in an expander.

You can include markdown content in expanders including code samples, embedded videos, bulleted lists, and more.

Copy and fill out for expanders
<details>
<summary>Title for the expander</summary>

Place long lists or lots of content in this section. The reader can expand/collapse as needed.

Add all content after Summary and before the closing details tags.

</details>
Example expander

Place long lists or lots of content in this section. The reader can expand/collapse as needed.

Code in a tip with line highlight
"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”.

Downloadable files

To link to a downloadable asset file, such as a .yaml, .json, or .xml:

  1. Drag and drop your file to the static/files folder. In this example, we'll drop in a file called domainCollector.ps1.
    header sizes
  2. Go to your doc in progress and use the following syntax to link the file:
<a href="https://help.sumologic.com/files/domainCollector.ps1" target="_blank">domainCollector.ps1</a>

Nearly all file formats are supported. For more information, see Docusaurus Static Assets.

If your file is available in another public Sumo Logic repo, provide the standard URL link. Here's an example.

Elements, UI

Not all UI elements have an intuitive name. It's the very nature of working with a constantly evolving product. Here are some examples:

IconTab NameDefinition
icon-recents.pngRecentsAccess recent content:
  • Content you’ve recently accessed.
  • Content recently shared with you.
icon-favorites.pngFavoritesContent you’ve marked as favorite.
icon-personal.pngPersonalContent you manage.
icon-library.pngLibraryList of all accessible content, including your creations and the content shared with you.
more-actions-kebabMore ActionsClick to reveal a menu with additional options.
nav-menu.pngNavigation MenuMain Sumo Logic menu containing your collectors, sources, library, help, and more.

When providing instructions that involve multiple UI elements, list them sequentially and in cascading order. For example: Click More Actions > Delete.

Emphasis

Bold

Use bold for UI elements you interact with, such as a button or tab.

Italics

Use italics for:

  • Defining a term the first time. For example, when defining a collector the first time, you would italicize once with the definition.
  • Providing content to enter into a field.

Underlines

Never underline text.

Emphasis, aka italics, with *asterisks* or _underscores_.

Strong emphasis, aka bold, with two **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough uses two tildes. ~~Scratch this.~~

Font

We use Lab Grotesque in our docs site and across all Sumo Logic media.

Headings

Use hashtags # to indicate the heading level and group content. Always start with H2 headers (##) in your doc body. Link anchors also generate automatically.

  • We mark a heading using a number of # for the level. This section is using an H3 heading, which is ### Headings.
  • Never use H1 (#) in your document. This is generated automatically by the page title (title: in frontmatter).
  • Headings should always be clean, plain text. Do not use bold, italics, or code ticks.
  • Be careful of using special characters. Dashes are ok, but try to avoid other punctuation.
## I'm an H2

### I'm an H3

#### I'm an H4

##### I'm an H5

###### I'm an H6

Headings must be used in correct order. The subsection of an H2 header would be H3 - you wouldn't jump to an H4 or H5. Skipping over a header level affects search and SEO structures to search crawlers like Google. Docusaurus carefully formats generated pages to ensure strong search and SEO, and malformed structures can reduce that strength.

Documenting procedures

When a topic provides instructions for a significant multi-step process, organize the content in sections with headings that signpost the nature of the information. Include "Step" in the heading to make it clear that the section is part of a larger configuration process. For example:

headers with steps

Hub pages

To generate a full list of docs within a folder, add this code to the file:

import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

## Guide contents

In this section, we'll introduce the following concepts:

<DocCardList items={useCurrentSidebarCategory().items}/>

This is best used in an index file. Include a list of all files and folders in that folder to the file. See any category file for a section in the site for how this looks.

Images

Add an image

  1. Save your image to the /static/img folder. This folder structure mirrors the doc section folders.

    • When updating existing images (like if there's a Sumo UI change), do not add a new version; always replace existing images. Image files take up a lot of room and can slow build times.
    • File format be .png or .gif.
  2. Add the import line to the top of your doc, underneath the front matter header, if it's not already there.

    import useBaseUrl from '@docusaurus/useBaseUrl';
  3. Copy the below code snippet and paste it where you want your image to appear.

    <img src={useBaseUrl('img/<your-image-file-path>.png')} alt="<your image description>" style={{border: '1px solid gray'}} width="<insert-pixel-number>" />
  4. Replace with file path above with your own image file path. The file path must start with img (do not preface it with /static) because Docusaurus builds and saves these static assets and serves from the baseUrl (or domain).

    info

    For web-hosted images, do not use the useBaseUrl syntax.

    • ✅ Do: <img src='https://sumologic-app-data-v2.s3.amazonaws.com/dashboards/Jira-OpenTelemetry/Jira-Catalina.png' alt="Catalina" />
    • ❌ Don't: <img src={useBaseUrl('https://sumologic-app-data-v2.s3.amazonaws.com/dashboards/Jira-OpenTelemetry/Jira-Catalina.png')} alt="Catalina" />
  5. Add alt text for your image (for example, "Image properties dialog" or "Sumo Logic logo"). This is a brief description of what the image is meant to show. Alt text is a label, not a caption, and doesn't need to describe all details of an image. If you are editing and you come across an image without alt text, add it!

    More about alt text

    Alt text, required under US Government GSA Section 508 regulations, is used by readers who cannot see images well or have software that reads the text aloud. It's also used by readers with slow internet connections who do not want to wait for images to download.

  6. Use the width to resize oversized and/or pixelated images, if needed.

<img src={useBaseUrl('img/sumo-square.png')} alt="Sumo Logic thumbnail logo" style={{border: '1px solid gray'}} width="150"/>

Image sizes

When sizing images, use your discretion.

Logos

For square logos, set the width to about 45-55px.

Yes ✅No ❌
alt-textalt-text

For wide logos (like in this doc), set the width to about 90-120px.

Screenshots

Ensure that screenshots are large enough so that the content is legible, but not comically oversized. Use your discretion.

Yes ✅No ❌
alt-textalt-text

Screenshots should never be wider than 600px.

Images in lists

When adding an image to a bulleted or sequential list, include the image snippet in-line with the list item, with a <br/> element in between, like this:

1. Here is a dinosaur.<br/><img src={useBaseUrl('img/docusaurus.png')} alt="alt-text" width="100"/>

Screenshots

Capture screenshots using SnagIt in .png format. Use SnagIt's border effect to apply a gray (RGB 212, 212, 212) four-point border.

By default, images that you insert into a page are set to be responsive - resized for the type of device the reader is using.

Masking sensitive information

We mask sensitive information like usernames, email addresses, and IP addresses. In Snagit or a similar program, use the shape tool to mask the text using solid gray, (RGB 212, 212, 212).

Callouts

Create callouts using the shape tool in SnagIt. Callouts should be red, 100% opacity, no drop shadow effect, 2 pts wide.

Lists

You can mix ordered (or numbered) and unordered (or bulleted) lists together. Use extra lines and tabs (or 2 spaces) to move content under these bullets, including other bullets, paragraphs, images, and more. Be careful of indenting too much; three tab indents will automatically render as code.

In a list item made up of an introductory word or phrase and an explanatory sentence or paragraph, separate the introductory text and the explanation with a period (.) rather than a dash (-). For example:

1. **Entity**. Select the Entity field in the Record that the resulting Signal should be associated with.
1. **Description (Optional)**. Define the description for the Signal.

Numbered Lists

Use numbered lists when providing a set of instructions or steps.

Always start with 1.. Markdown automatically numbers sequentially when building the site. This can be helpful when you need to add or change the order of instructions (no need to edit every number).

Markdown Ordered List
1. First ordered list item.
1. Another item.
- Unordered sub-list.
1. Actual numbers do not matter, just that it is a number.
1. Ordered sub-list.
1. And another item.

More content for this entry. And a screenshot:<br/> ![span hover](/img/apm/traces/span-hover-view.png)

Bulleted Lists

Use bulleted lists when the items do not need to be presented in sequential order. End each bullet in a terminal period. Use asterisks * for unordered, bulleted lists.

Markdown Unordered List
* Unordered list line 1.
* Line 2.
<br/>Content to show under 2.
* Another set of bullets.
* Here we go, another!

You can configure your editor to always use this format for lists. For Visual Studio Code, configure the following settings:

  • Ordered List: Marker set to one.
  • Unordered List: Marker set to *.

Ensure parallel grammatical structure - that is, start each bullet with the same part of speech.

When linking to Sumo Logic docs, use relative file paths. For external links, use absolute URL paths.

Whenever possible, use link text that’s relevant - such as the page title - rather than just "click here". If the link title is too long, you can either edit the title or summarize the content in a few words.

Linking to other headers in the same file

Here's how to make a [table](#tables).

Linking to files in the same folder

* Check out our [glossary](glossary.md); or
* Check out our [glossary](./glossary.md); or
* Check out our [glossary](/docs/contributing/glossary).

Linking to files in other parent folders

* Learn how to [sign up with Sumo](../get-started/sign-up.md); or
* Learn how to [sign up with Sumo](/docs/get-started/sign-up).

Linking to external URLs

For more information, see [Export Logs to Sumo Logic](https://auth0.com/docs/extensions/sumologic).

Markdown

Markdown is a simple, text-based format you can write using text editors, IDEs, or the GitHub website to write content. We use Docusaurus to manage, style, and build our site. We use GitHub-flavored Markdown, with some additional options. You can find more info at:

File naming convention

A Markdown file has a filename and extension of .md. We recommend keeping the filename short. It does not affect the canonical link.

Metadata (Frontmatter)

Markdown documents have metadata (e.g., title, description, and search keywords) at the top called frontmatter. Every page should have an id used for sidebar navigation.

---
id: page-id
title: Page title
sidebar_label: Navigation title
description: Learn more about...
keywords:
- metrics
- traces
tags: [apm, metrics]
---
ParameterDescription
id:(Required) Id for the page used in the sidebar and as the canonical link. Keep it short and only use dashes.
slug:(Optional) Overrides the id: for the canonical link. Best used for index pages for sections.
title:(Required) For SEO, be sure to use main keywords in your title and keep it under 60 characters. This title is used in navigation if a sidebar_label is not included.
sidebar_label:(Optional) Use a different title for the side navigation. Keep this title short. It does not affect the canonical link or page title.
description:(Optional) 1-2 sentences describing what the user will find in the doc. It appears in search engine results. If omitted, search engines will pull the first couple of sentences instead.
keywords:(Optional) List of page keywords, which boosts SEO.
tags:(Optional) A string or list of tags that adds a label and permalink to tag to help with sorting.

For a full list of options, see Docusaurus Markdown front matter.

Top-level navigation content is controlled in our docusaurus.config.js file.

Our sidebars.ts file controls the sidebar navigation for the entire site. It consists of multiple sidebars and sections based on the Guides top navigation, drilling down per guide. A list of sections and advice on content is at the top of the sidebars file, with comments throughout.

  • To add a specific page, you include the directory path and topic id from the frontmatter. For example, this page is contributing/style-guide.

  • To add a section within a section, use a category section with page links in it (see below example).

  • To add an index for a section, create an index.md page in the folder. Give it a slug: name where the name is the folder for the entire section like contribution-guide. In the category, use a link line with the folder name and index for example: link: {type: 'doc', id: 'contributing/index'},.

  • To add a new page, make note of the file path and id. For example, this document is located in the folder contributing with an id of create-document. When adding this file to the sidebar, it would be added to the contributing/create-document.

    Example: add contribution/create-document to sidebars.ts
    sidebars.ts
    //Contribution guide for documentation
    contributing: [
    {
    type: 'category',
    label: 'Contribution Guide',
    collapsible: true,
    collapsed: false,
    link: {type: 'doc', id: 'contributing/index'},
    items: [
    'contributing/create-document',
    'contributing/build-deploy',
    'contributing/translations',
    {
    type: 'category',
    label: 'Templates',
    collapsible: true,
    collapsed: false,
    items: [
    'contributing/templates/partner-app-doc'
    ]
    }
    ],
    },
    ],
  • To add a category, or dropdown list of documentation, use the following format:

    Example: add sidebar category example with additional section
    sidebars.ts
        {
    type: 'category',
    label: 'Name of Guide',
    collapsible: true,
    collapsed: false,
    link: {type: 'doc', id: 'foldername/id-first-page'},
    items: [
    'foldername/doc-id1',
    'foldername/doc-id2',
    {
    type: 'category',
    label: 'Section in Guide',
    collapsible: true,
    collapsed: false,
    link: {type: 'doc', id: 'foldername/id-section'},
    items: [
    'foldername/doc-id3',
    'foldername/doc-id4',
    ]
    }
    ],
    },
  • To add a dedicated sidebar, use the following format:

    Example: adding a dedicated sidebar for a guide
    sidebars.ts
    module.exports = {
    sectionName: [
    {
    type: 'category',
    label: 'Name of Guide',
    collapsible: true,
    collapsed: false,
    link: {type: 'doc', id: 'foldername/id-first-page'},
    items: [
    'foldername/doc-id1',
    'foldername/doc-id2',
    {
    type: 'category',
    label: 'Section in Guide',
    collapsible: true,
    collapsed: false,
    link: {type: 'doc', id: 'foldername/id-section'},
    items: [
    'foldername/doc-id3',
    'foldername/doc-id4',
    ]
    }
    ],
    },
    {
    type: 'category',
    label: 'Name of Another Guide',
    collapsible: true,
    collapsed: false,
    link: {type: 'doc', id: 'otherfoldername/id-first-page'},
    items: [
    'otherfoldername/doc-id1',
    'otherfoldername/doc-id2',
    {
    type: 'category',
    label: 'Section in Another Guide',
    collapsible: true,
    collapsed: false,
    link: {type: 'doc', id: 'otherfoldername/id-section'},
    items: [
    'otherfoldername/doc-id3',
    'otherfoldername/doc-id4',
    ]
    }
    ],
    },
    ]

Patents and trademarks

Protecting our patents and trademarks is important to do correctly. We do not want to expose the company to a loss of trademark or patent just because we didn't list it correctly.

This is a partial list of trademarked terms, which should be capitalized exactly as shown below.

  • Sumo Logic
  • Big Data for Real Time IT
  • Log Reduce
  • Elastic Log Processing
  • Push Analytics

Never use Sumo Logic in the plural or possessive form.

Punctuation

Punctuation is placed outside of quotation marks, British English style. For everything else (dates, times, spelling), we use American English style.

Commas

We use the Oxford (serial) comma. For example, use "I had eggs, toast, and orange juice", not "I had eggs, toast and orange juice".

Release Notes

Keep release notes concise with links to documentation and images for updated UI elements. You're welcome to add frontmatter such as tags and keywords.

Add your release note in the appropriate blog folder (blog-collector, blog-cse, blog-developer, blog-service) found at the top level of sumologic-documentation. Those folders correspond to the different release note sections:
Release notes menu

Text only

To add release notes without images:

  1. In the blog folder, create a new markdown file with the following name format: YYYY-MM-DD-product.md.
  2. Add the following frontmatter, swapping out these example values with your own.
    ---
    title: New XYZ Feature
    hide_table_of_contents: true
    image: https://help.sumologic.com/img/sumo-square.png
    keywords:
    - alerts
    authors:
    - url: https://help.sumologic.com/release-notes-service/rss.xml
    image_url: /img/release-notes/rss-orange.png
    ---
    • title. Title for release note.
      note

      For Service Release Notes only, append the title with the category name in parenthesis (example: Automatic Log Level Detection (Search)). See previous Service Release Notes for category names.

    • tags. Add a comma-separated list of existing tags.
    • hide-table-of-contents. Hide the TOC on the page, keeping the notes clean and wide on the page.
  3. Document the release notes. Add links, bullets, and images as needed.

Long Release Notes

For lengthy release notes, we recommend introducing the notes and adding a truncate line (<!--truncate-->), followed by the full set of release notes.

Text and Images

To add release notes with images:

  1. In the blog folder, create a new folder with the following name format: YYYY-MM-DD-product.
  2. In the new folder, create a markdown file named index.md. Add your release notes with frontmatter:
    ---
    title: Product or Feature Name
    tags: [apps, tracing]
    hide_table_of_contents: true
    ---
    • title. Name of the release notes including Product or Feature
    • tags. Add a comma-separated list of existing tags.
    • hide-table-of-contents. Hide the TOC on the page, keeping the notes clean and wide on the page.
  3. Save images to this folder and add them to the markdown file: ![alt text](image-name.png).

Reusing Content

For repeatable content (like an identical section that appears in several docs), you can save a lot of time by creating one instance of that content in the /docs/reuse folder and then import that snippet to other docs.

  1. Create a new markdown file and save it to the /docs/reuse folder.
  2. Import that content to another doc by adding this snippet (substitute the file path and object name with your own).
    import RestartC2C from '../reuse/restart-c2c-source.md';

    <RestartC2C/>

Headings in the reuse folder will not appear in the right-side nav in docs where they're imported. For this reason, unless the headers are H4 or below, reuse the content only but retain headings in the other docs.

Example: the content under the Cloud-to-Cloud source docs > Restarting Your Source section (example) lives in the reuse folder. The H3 headers live in the actual docs, and H4 headers live in the reuse file:

### Restarting your source

import RestartC2C from '../reuse/restart-c2c-source.md';

<RestartC2C/>

Tables

Simple tables can help format content. For example, lists of attributes with descriptions. Adding the style below the table helps with formatting.

Tables use plain markdown with one header, default left-aligned columns, and multi-colored rows. You can use Markdown for links and images. To break up content, you can use <br/> for line breaks.

| Column Name | Example Value | Description |
| :-- | :-- | :-- |
| Trace ID | ffaf2f69ee8ad0c1 | The unique identifier of the trace. |
| Root Service | api | The service that started the trace. |
| Started At | 07/27/2020 09:01:04.533 | When the trace started. |
| Duration | 12.582 ms | The amount of time the trace spans. |
| Number of spans | 35 | A trace consists of spans. This number tells you how many spans are in the trace. |
| Duration Breakdown | ![breakdown](/img/apm/traces/breakdown.png) | Each color indicates a service. The colors assigned to services are always the same on your account. You can change the color in the span summary tab after clicking on the individual span in trace view.<br/>Hover over to view a percentage breakdown of how long each span covers in the trace.<br/>![span hover](/img/apm/traces/span-hover-view.png) |
| Number of errors | 0 | The number of errors in the trace. |
| Status | 200 | The HTTP status code of the trace. |
Colons can be used to align columns.

| Tables | Are | Cool |
| :------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |

There must be at least 3 dashes separating each header cell.
The outer pipes (|) are optional, and you do not need to make the
raw Markdown line up prettily. You can also use inline Markdown.

Markdown | Less | Pretty
--- | :--- | :---
*Still* | `renders` | **nicely**
1 | 2 | 3

Docusaurus also supports HTML tables.

Tabs

Use the following code to create tabbed content. You can use Markdown in these tabs, including text, code content, images, and more.

At the bottom of the Markdown file, add the following code:

Copy and paste once into markdown file
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

For each set of tabs, use the following code:

Copy and paste into markdown for each tab set
<Tabs
className="unique-tabs"
defaultValue="tab1"
values={[
{label: 'Tab 1', value: 'tab1'},
{label: 'Tab 2', value: 'tab2'},
]}>

<TabItem value="tab1">

Add content here for first tab.

</TabItem>
<TabItem value="tab2">

Add content here for second tab.

</TabItem>
</Tabs>

See the following tabbed code examples:

Setup a Source in Sumo Logic:

Navigate to Collection management (Manage Data > Collection) Use an existing Hosted Collector, or create a new one. Next to the collector, select “Add Source”. Select “AWS Kinesis Firehose for Logs” Enter a Name to identify the source. Enter a Source Category following the best practices found in “Good Source Category, Bad Source Category”

Deploy the Cloudformation Template to Create a Kinesis Firehose Delivery Stream:

  1. Download the Cloudformation template.
  2. Open CloudFormation in AWS.
  3. Create a new stack using the CloudFormation template you downloaded.
  4. Provide the URL you created from your Sumo source.
  5. Select an S3 bucket to deliver failed logs, or create a new one.
  6. Click next.

Accept the IAM permissions, and create the stack.

SEO

For clarity and search engine discoverability:

  • Doc titles are very important for SEO. Use primary target keywords, try to mention "Sumo Logic", and keep length under 60 characters.
    • Example: Monitoring with the Observability SolutionMonitoring with Sumo Logic Observability
  • Use H2 sections to break up content and try to use primary keywords here as well.
    • Example: AWS Observability Solution.
  • H3 and H4 headers do not impact SEO as much. Use short, meaningful titles for readability and search.
    • Example: System architecture and monitoring.
For internal contributors
  • If you change a URL, set up a redirect so that users don’t get a 404 page.
  • Use Google Analytics to make data-driven decisions.

Videos

To embed a YouTube video on a doc:

  1. Copy and paste the following code into your page (including the import Iframe line).
    <Iframe url="https://www.youtube.com/embed/abcde12345?rel=0"
    width="854px"
    height="480px"
    id="myId"
    className="video-container"
    display="initial"
    position="relative"
    allow="accelerometer; autoplay=1; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowfullscreen
    />

    import Iframe from 'react-iframe';
  2. Remove the URL ID from the snippet (abcde12345) and replace it with your own video ID, which you can find in the YouTube link URL.
  3. Ensure that ?rel=0 is appended to the end of the URL. This ensures that only videos from the current YouTube channel will be suggested to the viewer after they've finished viewing the embedded video.
<Iframe url="https://www.youtube.com/embed/ZcbHoC1jZz4?rel=0"
width="854px"
height="480px"
id="myId"
className="video-container"
display="initial"
position="relative"
allow="accelerometer; autoplay=1; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
/>

import Iframe from 'react-iframe';

React components

MDX

MDX can make your documentation more interactive and allows using any React components inside Markdown:

export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '20px',
color: '#fff',
padding: '10px',
cursor: 'pointer',
}}
onClick={() => {
alert(`You clicked the color ${color} with label ${children}`)
}}>
{children}
</span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

This is <Highlight color="#1877F2">Facebook blue</Highlight> !

This is Docusaurus green !

This is Facebook blue !

Mermaid Charts

Mermaid provides sequence diagrams, charts, and more. Use these charts to detail processes, workflows, inheritance, and more. See the Mermaid guide for specifics and examples, and use the live editor to generate code.

See the following example code for adding Mermaid charts. You need to include the import line once per page.

Mermaid Example Code
<Mermaid chart={`
graph LR;
A-->B;
B-->C;
B-->D[Example Label];
`}/>
import Mermaid from '@theme/Mermaid';
graph LR; A-->B; B-->C; B-->D[Example Label];
Status
Legal
Privacy Statement
Terms of Use

Copyright © 2024 by Sumo Logic, Inc.