Tech Writer workflow

This document will guide you through the entire workflow for editing the New Relic documentation site as a New Relic Tech Docs Writer.

Resources

• VSCode (or another text editor)
  • VSCode has great GitHub integrations
• GitHub account
• GitHub Desktop

Edit in the GitHub web editor vs local build

Need to edit a doc? Use this table to decide where to work!

Continue reading for instructions on how to edit a doc locally.

1. Set up your local environment

Running the site locally makes testing and previewing large changes much easier. Here's how to get setup:

1. Install GitHub Desktop
2. Sign in to GitHub Desktop.
   • 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.
3. Navigate to the Docs Site repository on GitHub.com.
4. Click the green Code button and then select Open with GitHub Desktop.
5. Choose the location where you want 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.

2. Run the site locally

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.

Prerequisites

• Install Node
• Install Yarn
  • npm install -g yarn

Build the site

1. In your terminal, go to your cloned repo, docs-website. For example:
   • cd ~/Documents/github/docs-website
2. Run yarn with the following commands: yarn && yarn start
3. The site will take a few minutes to build. Make yourself some tea or coffee.
4. Once it's built, you can access your preview site in your browser by navigating to http://localhost:8000/

3. Edit a doc

Once your local environment and branch are set up, you're ready to edit a doc. Check out the style guide for writing guidelines.

1. First, ensure your Current Branch in GitHub Desktop is set to the correct branch, not Develop.
2. Navigate to the doc you want to edit in Finder. If I wanted to edit a Python agent doc, I would navigate to: ~/Documents/github/docs-website/src/content/docs/agents/python-agent/hosting-services/python-agent-stackato.mdx
3. 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
4. Save the file with your edits, then follow the same process for any other docs you wish to edit.

4. Commit your changes

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.

1. Navigate to GitHub Desktop. The left column should have a record of all the edits you have made to docs.
2. 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.
3. Click Commit to [yourbranchname]

5. Publish your commits

Once you have committed your changes, you're almost ready to open your Pull Request.

First, you need to ensure your branch is pushed upstream.

1. On GitHub desktop, click the blue Publish Branch button if available.
2. 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.

6. Open your pull request

Now that your commits are available to everyone, you need to notify people that your changes are ready to be merged into the develop branch.

To do this, you open a pull request:

1. On GitHub Desktop, click the blue Create Pull Request button.
2. This will open GitHub in your browser, and prompt you to fill in your pull request. Ensure you're merging from your branch into either the main or develop branch. If you scroll down, you can review all your commits to ensure they reflect all your changes.
3. 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 (GitHub issue link or Jira issue ID, SMEs, etc.)
   • To request a review from another Tech Writer: in GitHub open the PR, navigate to the Conversation section, and then select or type in a reviewer name in the Reviewer section.
4. Add any relevant labels to your PR. If you do not add from_tw, the PR will not be automatically assigned to another writer for review.
5. Once you're satisfied with your pull request, click the green Create pull request button.
6. 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.
7. At the bottom of the pull request page, you will see a Checks section. These checks ensure your PR doesn't break the build process of the site. Ensure all checks marked required pass before merging.
8. 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 don't add the from_tw label when you first create a PR, it will not automatically assign a reviewer. If you forget to add the label before opening the PR:

1. Add the from_tw label.
2. Turn the PR into a draft PR.
3. Select the PR is ready for review button at the bottom of the page to reopen the PR. The PR should now have a reviewer.

Preview a doc

There are two main ways to preview branches you’ve already published and run commits on:

• Local: Quicker, but requires a semi-substantial amount of setup and familiarity with a terminal.
• Gatsby Cloud: Full preview of the live site with no overhead, and a very convenient way to share a preview of your draft with a SME. Gatsby Cloud will comment on your PR with a link to a preview version of the site once the build is ready. Building the site generally takes about 15 minutes, but can sometimes take longer if there are a lot of changes.

Revise and publish a doc

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.

1. Respond to any comments in the file. Either reply with follow up discussion, or click Resolve conversation.
2. 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.

Revert merging

Remember that you can almost always undo things. If you merge a PR, and then find that you shouldn’t have, you can unmerge with the Revert button.

1. On the Pull requests tab in GitHub, click Closed on the tally bar to see all the issues and PRs that have alredy been merged.
2. Locate the PR you merged, and locate the Revert button.
3. Click Revert. That creates a new PR, which needs to be merged. If you want to reopen it, you need to follow the link back to the original PR and either revert that or reopen it.

Writers only: Work on a branch, not a fork

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:

1. Open GitHub Desktop
2. Click on Current branch: xxx
3. Click on New Branch
4. 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.

When you create a new branch, don't forget to add the Jira ticket's key (DOC-1234) to the branch name and the PR title.