edit-doc.md

id	title	sidebar_label	description
edit-doc	Edit an Existing Sumo Doc	Edit a Doc	Learn how to edit a doc, write content in markdown, and submit your changes to our repo.

Here's a high-level overview of how to edit an existing Sumo Logic doc.

{@import ../reuse/doc-prerequisites.md}

Minor edits

To submit a bug fix or another minor edit:

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. Apply your edits to the file.
3. Scroll to the bottom and select Create a new branch for this commit and start a pull request.
4. In the field underneath, enter a name for your branch and click Propose Change.

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

Major edits

If you'd like to submit more extensive edits, 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 repository

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

:::tip 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 3: 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 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."

1. Set permissions to allow maintainers to edit and update the PR (learn more).
2. Push your branch to the forked repo.
3. Visit GitHub 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.
4. On the Pull Request page, enter the following:
   • Make sure the base branch is main and compare branch is the one you pushed.
   • Enter a title for the PR.
   • If applicable, add issue number from Jira or similar program
   • Describe your updates.
   • Apply a label that best describes your contribution.
5. [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.
6. Click Create Pull Request.
   
7. 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.