The Docs team welcomes your contributions, whether you're a New Relic employee or a New Relic user. This doc walks you through three different methods for making or requesting changes to the docs site.
Prerequisites
Whatever method you choose, you need to sign up for a GitHub account if you haven't yet.
GitHub is at the heart of our whole process. When you propose a change to the docs site, GitHub manages the two different versions of a doc: the original version as it exists on docs.newrelic.com and the edited version that exists on your screen. With any edit you make, the Docs team reviews and approves it before it's published.
Tip
If you're a New Relic employee, we recommend joining the New Relic org on GitHub. To join the org, ping the @hero in our #help-security-tooling channel.
Contribute to the docs site
You don't need a complete understanding of git or GitHub to get set up, but you might encounter some unfamiliar terms:
- A commit acts like a save.
- A branch houses your commit(s).
- A pull request packages your branch and sends it to us to review and publish.
For most cases, we recommend editing the docs site via your browser. On every page, you can click Edit this doc to edit directly from your browser.
Click Edit this doc
On the doc you'd like to edit, click Edit this doc from the right nav. This opens a text view of the doc in question, letting you view the copy alongside its code.
Make your edits
Click the edit button (it's the pencil icon) in the top right. This lets you interract with the doc in edit-mode rather than the default view-only mode.
Make any changes you like. Don't worry about formatting or grammar — that's what your Docs team is here for.
Apply your changes
Once you're ready to save your progress, click the Commit changes... button. This brings you to a page that looks like this:
Let's break down what this form is asking:
Commit message: Required. A commit message is a brief explanation of what you changed. For example, one might read like:
Updated requirements and added content to install procedures
Extended description: Optional, but can be used for additional context:
Existing install procedures caused customer confusion
.Always choose Create a new branch for this commit.... We won't accept any contribution made directly to
develop
.There are no hard and fast rules about how often you should commit. You can make as many or as few commits as you'd like.
Navigate your new pull request
Your changes—that is, your branch and its commits—will be packaged into a pull request. This creates a working space for you and anyone who wants to review your work. Here's an example pull request page:
The two main areas are Conversation and Files changed.
- The Conversation tab lets you see status updates of your pull request and a preview of the doc. You can also leave comments.
- When your edits are still in progress, you might consider keeping the pull request in a draft state. This lets the team know that it's not ready for review yet.
- When you're ready for a review, scroll to the bottom of the Conversation tab and click the Ready for review button. This will ensure that the Docs team will see, review, and approve your contribution.
- You can find the comment box at the bottom of the page, too. Many contributors leave updates about the status of their work, like when they'd like their contributions reviewed and released, or if there are any blockers to the work's progress.
- The Files changed tab lets you review or continue your work. Click the ellipses to open up the text edit view. You can continue to make commits from this tab.
Wait for a docs review
The Docs team will assign the pull request to one of our tech writers when it's in review. You can track the status of your pull request from Projects in the right nav. Make sure to return to your pull request for any changes requested or follow-up questions from a writer.
After we've reviewed and approved your PR, you'll see a purple button that says Merged. At this point you'll see your changes reflected on the live docs after our scheduled releases. We have them three times a day: morning, afternoon, and evening.
If you want an end-to-end demo of this process, watch our video:
You can also copy a version of the docs repo to your GitHub account and local machine. This gives you more flexibility in exchange for some upfront work. A typical contributor who works this way may edit in VS Code and make commits and file pull requests via GitHub Desktop.
This process has three broad phases:
You fork, or copy, the docs site repo to your GitHub account and local machine.
You sync your version of the docs repo with the real version of the docs repo. This is an important step. The Docs team will not receive your PRs if you do not sync your fork with our repo.
You submit a test PR to confirm you've completed these steps successfully.
If you're choosing this method, we recommend that you install GitHub Desktop. This is a GUI that handles git commands for you so you don't need to open your CLI after set-up.
Edit the site locally
From the docs-website repo, click the Fork button. GitHub will prompt you to choose an owner, repo name, and description.
Clone your copy to your local machine
From your GitHub account profile, find your newly copied
docs-website
repo. Click the Code button and copy the HTTPS URL. Open your CLI.You need to choose where you want the docs site to live.
- If you want your copy to live in your Documents folder, for example, then you'd run this command to ensure that your copied repo goes to your Documents folder:
cd <YOUR_PATH_TO_FOLDER>
. - Using the HTTPS URL you copied from the previous step, run this command:
git clone <YOUR_PASTE_OF_HTTPS_URL>
Connect your copy with the original docs repo
If you tried to create a PR at this stage, you'd only be changing your version of the docs site — the Docs team wouldn't receive your PR. The following steps establish a connection between your fork and the original docs repo, a process called syncing upstream.
Go to the docs-website repo and click the Code button. Copy the HTTPS URL just as you did in the previous step. Unlike the last step, however, you're copying the HTTPS URL of the docs repo, not your fork.
From your CLI, change directory to the location of your cloned fork. For example, if you copied to your Documents folder, the command would read:
cd <YOUR_PATH_TO_DOCUMENTS_FOLDER>/docs-website
Run
git remote -v
Run
git remote add upstream <HTTPS_URL_HERE>
Run
git remote -v
to confirm you successfully added the upstream repo. You should see something like this, which is a different print from what you saw in step 3:git remote -vorigin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)
Set up GitHub Desktop to create pull requests
At this stage, we recommend you open up GitHub Desktop to edit the docs site rather than using git from your CLI. If you're a git wiz, then you can skip this step and file your first pull request.
From GitHub Desktop, go to File, then click Add local repository. Use the finder to add your clone of the docs site. To create a test pull request:
Create a new branch.
Open the
docs-website
folder in VS Code or an editor of your choice. Make sure you're working on your new branch.Make an edit to any doc and save your changes. In GitHub Desktop, you should see your changes reflected in the Changes tab.
In the Summary (required) field, describe your changes. If you're just making a test edit, you can write: Test pull request, do not merge. Click Commit.
Follow the prompts in GitHub Desktop to file the pull request. GitHub will open in your browser. Make sure the
base
is set todevelop
.
Congratulations! You're done. A good thing to keep in mind is to routinely Fetch origin from GitHub Desktop. This keeps your fork updated with the upstream repo.
Now that you've successfully forked the repo, you have the option to collaborate with people on their existing branches. Check out our video tutorial for what this looks like:
- If you want your copy to live in your Documents folder, for example, then you'd run this command to ensure that your copied repo goes to your Documents folder:
You have a few different options for making a request to the team:
If you're a New Relic employee, you can ping the @hero at our documentation help channel. Our hero is a dedicated interruptible person, who publishes doc edits and answers doc questions.
You can submit a Jira request. From the right nav, click one of the buttons in the Was this doc helpful? element.
You can file a GitHub issue from the docs site repo. In the top-most nav under the search box, click Issues, then New Issue.
You can expect follow-up on your request based on this timeline:
Type
SLA
Notes
Small self-service edits
1 business day
A "smaller" edit is any edit that is a few sentences or less. The majority of self-service edits fall into this bucket.
Larger self-service edits
3 business days
A larger edit is any edit that is a few sentences or more, or any edit that involves an all-new doc. When you submit a "larger" edit, the Docs Hero will create a docs Jira on your behalf, notify you with a link, and place that ticket at the top of our Jira board.
Requests for Docs team to update docs
2+ weeks lead time for Tech Docs team
Our team works in one-week sprints. Time-sensitive requests should be made at least two weeks in advance for "ordinary" features (roughly, MMF-sized features), and at least six weeks in advance for "larger" features (roughly, milestone-sized projects).
A good request includes a link to the doc(s) in question and a brief explanation about the nature of the problem. For example, letting us know if install procedures are out of date or unclear.
Create a new doc
To create a new doc:
- Clone the repo on your computer.
- In
/src/content/docs/
, find a good location for your doc. - Create a new .mdx file or copy an existing doc in your text editor.
- Write your content.
- Optional: Add your doc to the right nav .yml file. The navigation files can be a bit hard to work with, so feel free to leave this step for a Docs writer to handle when they review your pull request.
- Commit your changes and create a pull request.
The Docs team has a hero waiting for new pull requests. We'll help you get the content finalized and make sure that it's in the right place.
Structure your docs with MDX components
As a contributor, any draft content you provide is more than appreciated—whether it's a skeleton draft of bullet points or the next great American novel. Still, the Docs team is always willing to structure, add images, update the nav, or provide copy edits per our style guide. You still might find these docs helpful, though:
- Check out our Basic template doc. We have other doc types and templates in this category as well.
- If you're unsure about capitalization, you can refer to our Capitalization guide for products and features. We don't expect perfection here! We can correct anything you send our way.
- We have a bunch of components that can structure a doc. Our contributors use collapsers and tables the most.
- You can add images as well. We're more than happy to add images for you, however.
Troubleshoot build errors
As a rule, the Docs team will always troubleshoot a failing pull request for you. When you submit a PR, it'll be assigned to a tech writer who oversees its progress from draft state to its release, including routine checks for any errors. That said, we have some best practices for common, simple errors:
- Doublecheck your Markdown, especially on tables or our components.
- Check your backticks,
“
s (curled) and"
s (uncurled). - Try closing and re-opening a PR. If this doesn't work, then leave a comment in the PR or, if you're a New Relic employee, ping the @hero.
Tip
More often than not, images are the likely cause to errors. If you've checked everything and the PR is still failing, chances are it's related to images. We'll step in and fix the PR for you.