Guidelines and Writing

Sumo Logic uses the following resources and guidelines to write content. If you have questions, contact us on Sumo Dojo Slack or ask in your pull requests.

Writing Style Guide

If you need help with a convention, word to use, format to follow, we will keep a cheatsheet of styles here! We also follow Microsoft Manual of Style.

Formatting Text

Cheatsheet when to use different formats. Here's the Microsoft Style Guide for User Input for more info.

• Use italics when defining a term the first time. For example, when defining a collector the first time, you would italicize once with the definition.
• Use bold for UI elements you interact with, such as a button or tab.
• Use italics for content to enter into a field.
• Use `code ticks` for inline code and triple ticks for blocks of code. This is important for scripts and CLI.

This is a great example for these styles: If you are not parsing all sources in the hosted collector with the same parser, click the +Add Field link, and add a field whose name is _parser with value /Parsers/System/Auth0/Auth0.

Headings

A heading is a great way to group content. When you use Google Docs or Microsoft Word, you select a drop-down menu to assign a heading format. We use # to create them. Use headings for concepts, steps in complicated procedures, and so on.

Here is a cheatsheet for those:

• We mark a heading using a number of # for the level. This section is using a heading 3 which is ### Headings.
• The title of the page is heading 1. Never use heading 1 (#) in your document. This affects Google and search engine results for the page.
• Headings should always be clean, plain text. Do not use bold, italics, or `code ticks`!
• Be careful of using special characters. We recommend not using most punctuation. Dashes are ok for headings.

Acronyms

All companies have numerous acronyms for product, 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.

Contractions

For writing in English, contractions feel like normal, everyday speech. But they can cause issues with translation, especially if someone uses Google Chrome translation or other tools and when we hire companies to translate content. We recommend not using contractions. Spell out all words. This includes don't, it's, haven't, and so on.

Active Voice

When writing instructions, it helps to always use active voice. 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.

Here is a cheatsheet:

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

Writing Resources

If you are new to writing content or would like to learn more, see these resources. The Sumo Logic Docs team will review submissions, provide suggested edits, add new content into the navigation, and answer any questions you have.

• 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 - Excellent and easy self-paced courses to refine your writing. Be advised, the courses may use a different style, but still excellent 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:

• Usability and Tech Writing - Jakob Neilson defined usability, including insights on technical writing and learning, helpful for writing docs
• FFeathers tech writing - Pioneered API and technical tech writing, insights and instructions
• I'd rather be writing - Guides and thoughts on tech writing process and content

This list of resources will grow!

Focused Content

These guidelines help you focus content and decide what to write per page:

• The introduction is the first paragraph someone reads. It should tell them what this 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, not too many screenshots.
• Include any notes, warnings, etc.

Markdown Style Guide

See Markdown Formats and Templates for examples, usage, and templates for Markdown. It is a simple, text-based format using text editors, IDEs, or the GitHub website to write content. We use Gatsby to manage, style, and build our site.