Create and Publish Sumo Logic Document

Here's a high-level overview of how to create a new Sumo Logic doc.

Prerequisites

• You must have a GitHub account to contribute to Sumo Logic documentation.
• We recommend adding 2FA protection when contributing to Sumo Logic repositories.

note

Help us keep Sumo Logic open and inclusive by reviewing our Code of Conduct.

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. Remember to sync your fork and update branches as needed.
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: <your initials>-apps-gitlab.

Step 2: Create a doc file

The docs site is comprised of 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. In the appropriate subfolder (e.g., /docs/metrics), create a markdown file in the format <your-file>.md.

Step 3: Add doc title and metadata

See Frontmatter to learn how.

Step 4: Write your doc

In your IDE, write the body of your doc.

• See our Style Guide to learn how to write and style content, add code snippets, import multimedia, and more. Doc body text content is written in GitHub-flavored markdown, with some customizations.
• See our recommended authoring tools.

Recommended authoring tools

If you're new to GitHub and/or writing Markdown, we recommend using the following apps (click to expand):

• Atom: Create new branches, stage and commit, push and pull, resolve merge conflicts, view PRs and more - all from within your editor. The GitHub package comes bundled with Atom.
• 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 and Mermaid Markdown Syntax Highlighting for charts and graphs
• iTerm2 - Terminal application for macOS. You can also install Oh My Zsh for theming.

Step 5: 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 6: 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 7: Preview your changes

Next, you'll build and deploy a local instance of the Sumo Logic Docusaurus site.

Our site is built using Docusaurus, a static site generator, which builds your site as simple static HTML, JavaScript and CSS files. To view our install installment requirements and preview your build, see Building Locally in our README.

We use Yarn for all installs and builds. Never use NPM commands for installing or updating packages.

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 don't 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.
   • Include an issue number from GitHub or Jira, etc.
   • 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.