Create or Edit a Doc

Discovered an error in a document? Learn how to submit a fix, along with a comprehensive guide on creating or editing a Sumo Logic document.

Prerequisites

• You'll need a GitHub account to contribute to Sumo Logic Docs.
• We recommend adding 2FA protection when contributing to Sumo Logic repositories.
• Help us keep Sumo Logic Docs open and inclusive by reviewing our Code of Conduct.

Quickstart

Submit a GitHub Issue

Short on time? You can report a bug or request more information by submitting a GitHub Issue to our repository. Enter as much information as you can, including content corrections, steps to reproduce, command/code updates, clarifying questions, and recommended fixes.

Before submitting an issue, you can browse our existing GitHub issues to see if someone has already reported it, and join the discussion via comments.

Submit a minor fix

Submitting a minor fix, such as correcting a typo, is very easy and can be done quickly without having to clone or fork your GitHub repository locally. Check out the instructions below.

Micro Lesson

Check out this brief tutorial on how to submit a basic change to our docs.

View text instructions

1. Scroll to the bottom of that doc and click the Edit this page link. This will open your selected doc in Edit file mode on our GitHub repo website.
2. Click Fork this repository to continue.
3. Apply your edits to the file.
4. Scroll down a bit on the page until you see the description field, enter a brief summary of your changes there, then click Commit changes.
5. In the Propose changes dialog, enter a description of your change, enter a new name for your branch if desired, and click Propose Change.

This will fork and submit changes to the Docs Team for review.

Edit a doc

Step 1: Fork the Sumo Docs repository

1. Fork the Sumo Docs repository locally. Remember to sync your fork and update branches as needed.
   GitHub tips

   • How to fork a repo
   • How to sync your fork with branches
2. Review our README documentation guidelines.
3. Create a new branch from your forked repo using a name that best describes the work or references a GitHub issue number. For example, if you wanted to submit a PR to edit our Elasticsearch app doc, you'd write something like: <your initials>-apps-elasticsearch.

New to GitHub and/or Markdown? Check out our recommended authoring tools.

• GitHub Desktop. Easy-to-use interface to update your local machine clone, create branches, push to GitHub, and more.
• VS Code. Development application to open the repo, edit and create files, and preview pages as you write. We recommend the following extensions:
  • Markdown All in One
  • Markdown Preview GitHub Styling
  • Markdown Preview Enhanced
  • Markdown Preview Mermaid Support and Mermaid Markdown Syntax Highlighting for charts and graphs
• iTerm2. Terminal application for macOS. You can also install Oh My Zsh for theming.

Step 2: Edit your doc

In your new branch, edit the doc markdown file. See our Style Guide to learn how to style content, add code snippets, import multimedia, and more. Doc body text content is written in GitHub-flavored markdown, with some customizations.

Step 3: Preview your changes

Before proceeding, you'll need to preview your changes.

1. Go to the Building Locally section in our README.
2. Review installation requirements.
3. Preview your build.

This constructs and deploys a local version of the Sumo Logic Docusaurus site. Our site relies on Docusaurus, a static site generator. It creates your site as basic static HTML, JavaScript, and CSS files.

We exclusively use Yarn for all installations and builds. Avoid using NPM commands for package installations or updates.

Step 4: Submit your request

1. Commit your changes to the branch with a meaningful message.
   Use descriptive commit messages (and issue or ticket numbers, if applicable) detailing the content updates you are entering for content. One-line messages are fine for small changes, but bigger changes should look like this:

   $ git commit -m "A brief summary of the commit
   >
   > A paragraph describing what changed and its impact."
2. Set permissions to allow maintainers to edit and update the PR (learn more).
3. Push your branch to the forked repo.
4. Visit our repo after pushing your branch. If you see an option to Compare & pull request for your branch, click this.
   
   • If you do not see it, create a new PR.
     1. Select main for the base branch. This is the branch all staging and production content builds from.
     2. Select your branch for the compare.
     3. Click Create pull request.
5. On the Pull Request page, enter the following:
   • Make sure base branch is main and compare branch is the one you pushed.
   • Enter a title for the PR.
   • If applicable, include a GitHub issue number (or, for internal Sumos, the Jira ticket number).
   • Describe what changed, new pages, updates.
   • Apply a label that best describes your contribution.
6. (Optional). For urgent, high-priority PRs (for example, doc edits tied to a GA release happening within 24 hours):
   1. Add the GA release date to the title. For example, AWS Integration release (GA: Jan 1, 2023).
   2. From the labels list, select the hot🔥 label, signifying it's an extremely urgent PR.
   3. For internal Sumos only: after completion of all GitHub checks, send your PR link to the #doc-int and #open-source Slack channels for review.
7. Click Create pull request.
   
8. First-time contributors will be prompted in a comment to sign our Contributor License Agreement. We allow individual contributions and contributions made on behalf of companies.
   

Create a new doc

To submit more extensive edits, such as creating a new doc, we recommend forking our repo, making changes in a new branch, and submitting a PR for review.

Feel free to reach out to the Docs Team to discuss. We're happy to work with you on the project and talk through rewriting content, changing flow, adding a new topic or section, and deprecating content.

Step 1: Fork the Sumo Docs repository

To create new doc, we recommend forking our repo, making changes in a new branch, and submitting a PR for review.

Feel free to reach out to the Docs Team to discuss. We're happy to work with you on the project and talk through rewriting content, changing flow, adding a new topic or section, and deprecating content.

1. Fork the Sumo Docs repository locally. Remember to sync your fork and update branches as needed.

GitHub tips

• How to fork a repo
• How to sync your fork with branches

1. Review our README documentation guidelines.
2. Create a new branch from your forked repo using a name that best describes the work or references a GitHub issue number. For example, if you wanted to submit a PR to edit our Elasticsearch app doc, you'd write something like: <your initials>-apps-elasticsearch.

New to GitHub and/or Markdown? Check out our recommended authoring tools.

• GitHub Desktop. Easy-to-use interface to update your local machine clone, create branches, push to GitHub, and more.
• VS Code. Development application to open the repo, edit and create files, and preview pages as you write. We recommend the following extensions:
  • Markdown All in One
  • Markdown Preview GitHub Styling
  • Markdown Preview Enhanced
  • Markdown Preview Mermaid Support and Mermaid Markdown Syntax Highlighting for charts and graphs
• iTerm2. Terminal application for macOS. You can also install Oh My Zsh for theming.

Step 2: Create a doc file

Our docs are GitHub-flavored markdown files containing content like bulleted instructions, screenshots, tables, interactive code samples, and more.

1. Open your new branch in your IDE and go to the /docs folder.
2. Create a new markdown file in the format <your-file>.md and save it to the appropriate subfolder. For example, if you're creating a new metrics doc, you'd save it to the /docs/metrics folder.
3. At the top of your file, add your frontmatter, which is the doc metadata. Follow the instructions under Frontmatter.

Step 3: Write your doc

In your Integrated Development Environment (IDE), compose the body of your document.

Refer to our Style Guide for instructions on crafting and styling content, including adding code snippets, importing multimedia, and more. The body text of your document is written in GitHub-flavored markdown, with some customizations.

Step 4: Add doc to the navigation menu

To add your new doc to the left-nav menu, you'll need to add its name and file path to the sidebars.ts file.

Doc Team Support

The Sumo Logic Doc Team can help you add your doc to the sidebar and top navigation. If you have suggestions, include those in your Pull Request description. If you add the documentation to the sidebar, the team will review the location and names for building and placement in navigation.

Step 5: Add doc to the hub page

Hub pages are /index pages that display all docs in that section in card view. Some cards are sorted by alphabetical order, and some are sorted by importance and/or ranking.

As an example, let's say you needed to add a Best Practices doc to the Send Data hub page.

Once you decide on placement, use the card HTML code in that doc to create a new entry.

Step 6: Create CID URL

We often encounter changes in links, so we assign each document a permanent URL, which includes a Content ID (CID) number. This permanent URL performs a 301 redirect to the canonical URL. This approach ensures that future modifications to the canonical URL, such as product name changes, do not affect the 'Learn More' links for users. Additionally, it reduces the need for code changes to the user interface, offering greater flexibility for making quick updates.

This URL is then placed in the UI in the appropriate place. For example, cid=0071 links to a metrics page, which appears in the product in the Metrics section as a help link.

To create a CID:

1. In your GitHub authoring tool (like Atom or VS Code), open our cid-redirects.json file, which contains all 301 redirects.
2. Scroll down to the CIDs section, where the line items start with "/cid/".
3. Find an unused CID number, then associate that CID value to your doc's file path. For example, if 5122 is unused, and your file path is /docs/metrics/chart:

Example

"/cid/5120": "/docs/metrics",
"/cid/5121": "/docs/metrics/introduction",
"/cid/5122": "/docs/metrics/chart",

Step 7: Preview your changes

Before proceeding, you'll need to preview your changes.

1. Go to the Building Locally section in our README.
2. Review installation requirements.
3. Preview your build.

This constructs and deploys a local version of the Sumo Logic Docusaurus site. Our site relies on Docusaurus, a static site generator. It creates your site as basic static HTML, JavaScript, and CSS files.

We exclusively use Yarn for all installations and builds. Avoid using NPM commands for package installations or updates.

Step 8: Submit your request

1. Commit your changes to the branch with a meaningful message.
   Use descriptive commit messages (and issue or ticket numbers, if applicable) detailing the content updates you are entering for content. One-line messages are fine for small changes, but bigger changes should look like this:

   $ git commit -m "A brief summary of the commit
   >
   > A paragraph describing what changed and its impact."
2. Set permissions to allow maintainers to edit and update the PR (learn more).
3. Push your branch to the forked repo.
4. Visit our repo after pushing your branch. If you see an option to Compare & pull request for your branch, click this.
   
   • If you do not see it, create a new PR.
     1. Select main for the base branch. This is the branch all staging and production content builds from.
     2. Select your branch for the compare.
     3. Click Create pull request.
5. On the Pull Request page, enter the following:
   • Make sure base branch is main and compare branch is the one you pushed.
   • Enter a title for the PR.
   • If applicable, include a GitHub issue number (or, for internal Sumos, the Jira ticket number).
   • Describe what changed, new pages, updates.
   • Apply a label that best describes your contribution.
6. (Optional). For urgent, high-priority PRs (for example, doc edits tied to a GA release happening within 24 hours):
   1. Add the GA release date to the title. For example, AWS Integration release (GA: Jan 1, 2023).
   2. From the labels list, select the hot🔥 label, signifying it's an extremely urgent PR.
   3. For internal Sumos only: after completion of all GitHub checks, send your PR link to the #doc-int and #open-source Slack channels for review.
7. Click Create pull request.
   
8. First-time contributors will be prompted in a comment to sign our Contributor License Agreement. We allow individual contributions and contributions made on behalf of companies.
   

What happens next?

Docs Team members will review contributions, provide feedback, and approve. When approved, the Docs Team will merge and update staging. Updates to production will be handled by the Docs Team.

Contact us

Need to get in touch? You can find us at:

• Sumo Logic Support
• Sumo Logic Community
• Sumo Dojo Slack