This document will guide you through the entire workflow for editing the New Relic documentation site as a New Relic Tech Docs Writer.
Install GitHub Desktop, and then navigate to GitHub Desktop's preferences. On Macs, click on GitHub Desktop in the top left corner of your screen and select Preferences. Select the blue Sign In button and follow the prompts in the browser window.
Once GitHub Desktop is set up, navigate to the Docs Site repository on GitHub. Click the green Code button and then select Open with GitHub Desktop. Choose the location where you the repo, and this will clone the entire repository to your local machine at the designated path. You can ensure the repo was cloned by navigating to your local GitHub folder (The default is
~/Documents/github). Once you have cloned the repo, you don't need to clone it again in the future.
Build the site locally using the Terminal to preview changes before opening a Pull Request. While it's highly recommended to build the site locally, this is technically an optional step. The site will automatically reflect any local changes once build. Node and Yarn are tools used to build the site on your local machine.
- Install Node
- Install Yarn
npm install -g yarn
- In your Terminal, go to your cloned repo, docs-website.
- Run yarn with the following commands:
- The site will take a few minutes to build. Make yourself some tea or coffee.
- Once it's built, you can access your preview site in your browser by navigating to http://localhost:8000/
Some teams work on branches, some teams work on forks; the docs team works in branches. As long as a branch has been pushed upstream, this allows us to work collaboratively and ensure that no work is ever lost when someone goes on vacation.
To create a branch on the docs-website repo:
- Open GitHub Desktop
- Click on Current branch: xxx
- Click on New Branch
- You will be prompted to name your new branch. Descriptive names are best. It's a great way to quickly clue people in to what your work is all about. For example, if you are working on What’s New pages, you might name the branch Whats-new-updates.
Once your local environment and branch are set up, you are ready to edit a doc. Check out the style guide for writing guidelines.
- First, ensure your Current Branch in GitHub Desktop is set to the correct branch, not Develop.
- Navigate to the doc you want to edit in Finder. If I wanted to edit a Python agent doc, I would navigate to:
- Edit the doc in your text editor of choice. You should write docs in markdown language. Reference the style guide for help with formatting markdown
- Save the file with your edits, then follow the same process for any other docs you wish to edit.
Once your edits are done, you can commit them. This stages your changes, which you will later push upstream to Github. By pushing your changes, everyone will have access to your branch and commits.
- Navigate to GitHub Desktop. The left column should have a record of all the edits you have made to docs.
- In the bottom left corner, name your commit and add a good description of your edits. It should be descriptive enough to ensure that someone can understand all the changes made by simply scanning this description.
- Click Commit to [yourbranchname]
Once you have committed your changes, you are almost ready to open your Pull Request.
First, you need to ensure your branch is pushed upstream.
- On GitHub desktop, click the blue Publish Branch button if available.
- If you don't see the Publish Branch, click the blue Push Origin button.
This will push all your commits upstream and make them available to everyone else through the GitHub repository.
Now that your commits are available to everyone, you need to notify people that your changes are ready to be merged into the
To do this, you open a pull request:
- On GitHub Desktop, click the blue Create Pull Request button.
- This will open GitHub in your browser, and prompt you to fill in your pull request. Ensure you are merging from your branch into either the
developbranch. If you scroll down, you can review all your commits to ensure they reflect all your changes.
- Just like your commit description, your pull request description should be detailed and give the full context of your changes.
- Feel free to add any additional context here (issue or Jira number, SMEs, etc.)
- Once you are satisfied with your pull request, click the green Create pull request button.
- You can either publish the changes directly by approving the pull request yourself, or you can request for another Tech Writer to peer edit it.
- To request a review from another Tech Writer: in GitHub open the PR, navigate to the conversation Conversation, and then select or type in a reviewer name in the Reviewer section.
- At the bottom the pull request page, you will see a Checks section. These checks ensure your PR does not break the build process of the site. Ensure all these checks pass before proceeding. The checks should finish within twenty minutes. If the Pull Request is urgent, you can skip the AWS Amplify Console Web Preview check.
- Once the pull request has passed the checks and it has been approved by another tech writer (or you are confident the changes are ready to be published), click the green Merge pull request button. This will merge your branch and commits into the repository and will begin the build process.
If you’re peer editing a doc or have been otherwise assigned to a PR as a reviewer, you have a few choices for how and where to do the work. The most streamlined and open-source approach is to do the edit using GitHub options, rather than copying the file to Google Docs and editing there.
For cases where you have questions and suggestions rather than straight copy edits, follow these steps.
- Open the PR that you’re assigned to review.
- On the Files changed tab, you can either:
- Click Review changes and then select one of the following:
- Comment - use if you have a comment that doesn’t require follow up.
- Approve - use if you just want to approve the PR. You can request changes in the Leave a comment area, and select Approve if you want to let the writer make the edits and merge the file without a follow-up review from you.
- Request changes - use for times when you want to make sure the changes you request are included. You’ll be notified with any updates that the writer makes.
- OR, start making comments on lines or sections of the doc. To do this, click the add comment icon , and leave an edit or comment for that specific line in the page. With this option, you get the choice between adding a single comment or starting a review. If you’re going to make comments throughout a doc, choose Start a review so the comments will all be rolled into one commit.
- Click Review changes and then select one of the following:
- Click Finish your review to complete your review. This triggers a notification to the writer alerting them that you’ve made suggestions.
If you have copy edits for a file rather than comments and suggestions, you can make the changes to the file in different ways. Here are two main options:
- Edit using the GitHub browser: on the Files changed tab, in the diff window click the editing button (three dots). When you finish your edits, add a comment at the bottom of the file and choose to either commit the changes directly, or create a branch and start a pull request. Choose to branch and start a pull request if you expect a writer to review the diff and accept or revise your edits.
- Edit locally: check out the branch containing the file you want to edit. In GitHub Desktop, click the Current branch down arrow and select the branch. Then, make the edits on your local drive, save, and commit your changes to the branch.
- Note that this approach adds your edits to the open pull request. You can now see the changes you added to the file on the Files changed tab in the PR.
These are just a few of many editing options. You’ll find your preferred way, just as you have with the Drupal tools.
If you’re notified that a reviewer has submitted a review to your file, go to your PR and review the changes. You might see them in the diff view, if they’re part of a review with comments; otherwise, they might appear as copy edits in the file.
- Respond to any comments in the file. Either reply with follow up discussion, or click Resolve conversation.
- When you’ve resolved all the comments, and all of the automatic checks have passed, you can merge the pull request. Merging the pull request sets in motion the automated build process and your changes will be published shortly.
Note: You will only be able to merge when the Merge pull request button is green. If it’s not green, review for any comments you missed, or other messages that indicate why GitHub is blocking you from merging.