create-doc.md

id	title	description
create-doc	Create a New Doc	Learn how to create a doc, write content in markdown, and submit your changes to our repo.

import useBaseUrl from '@docusaurus/useBaseUrl';

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

Prerequisites

import DocPrereq from '../reuse/doc-prerequisites.md';

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.

:::tip Recommended authoring tools

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

• 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
• GitHub Desktop: Easy-to-use interface to update your local machine clone, create branches, push to GitHub, and more.
• 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.

:::note 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.
<img src={useBaseUrl('img/contributing/hub-card-style.png')} alt="icon" />

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

Step 7: Create CID URL

Because docs links appear throughout our product, and canonical links often change, we assign each doc a permalink URL containing a content ID (CID) number. The permalink URL does a 301 redirect to the canonical URL. This way, future changes to the canonical URL (such as a product name change) won't impact the Learn More links for the user. And it will save us code changes to the UI, providing great flexibility when we need to make quick changes.

This URL is then placed in the UI in the appropriate place. For example, https://help.sumologic.com/?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 add that value along with the canonical URL. For example:

"/cid/5120": "/docs/manage/users-roles/roles/create-manage-roles",
"/cid/5121": "/docs/example",
"/cid/5122": "/docs/get-started/library",

Ideally, although not required, this should be placed near URLs similar to the one you're adding.

Step 8: 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 9: 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.