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.

0. Set up your local environment

You only need to set up your local environment once. If you've already done this, you can skip this step.

Go here for detailed instructions on how to set up your local build environment.

1. Create a branch and edit the docs

In GitHub Desktop, you will see three tabs labeled Current Repository, Current Branch, and Fetch origin. The default branch is Develop, so it's time to create a branch.

1. Click on Current Branch and select New Branch.
2. Find a doc you want to edit.
   • Use Finder or File Explorer with the file path. For example, if you wanted to edit a Python agent doc, you 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 with markdown language.
4. Save the file with your edits.

Check out the rest of our style guide for any questions about writing guidelines.

2. Commit your changes

Even though you've saved your edits, you still need to make a commit. You can think of a commit like a checkpoint in your workflow. The commit process begins with staging and ends when you push your changes to GitHub.

1. Navigate back to GitHub Desktop and check out the left column. In Github Desktop the left column shows:
   • A record of all new edits made to any docs
   • A blue button that says Commit to [your-branch-name]
2. Name your commit and add a description.
3. Click Commit to [yourbranchname].
   • The commit name and description could look something like feat(PythonAgent): Renamed the section heading

3. Run the site locally

Build the site locally using the terminal. While this step is optional, it is highly recommended to build the site locally and preview the changes before opening a pull request.

You only need to rebuild the local site when it crashes, not after every save or commit.

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 built, preview the site in your browser by navigating to http://localhost:8000/

4. Publish your commits

Once you're satisfied with your changes, push your commits to GitHub. This makes them available to everyone else in the GitHub repository.

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.

5. Open your pull request

While your commits are viewable by everyone, your edits won't be merged into the develop branch until another writer has reviewed them.

To do this, you open a pull request (PR):

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 the develop branch.
   • Scroll down to review all your commits.
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.)
   • Request a review from another tech writer by opening the PR, navigating to the Conversation section, and inputting the reviewer's name in the Reviewer section.
4. Add the from_tw label and any other relevant labels to your PR.
   • If you don't add from_tw, the PR won't be automatically assigned to another writer for review.
5. Once you're satisfied with your PR, 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.

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.
• Netlify 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. Netlify 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.

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 issue ID (DOC-1234) to the branch name and the PR title.

A note about GitHub permissions

Writers on the Docs team work in branches, but contributors outside of the Docs team use forks. This also means that non-Docs contributors can't edit content on a branch directly, which can make collaboration tricky.

GitHub permissions are used to determine who can work on a branch and who can work on a fork. On GitHub, access is determined by team and member roles. Although anyone can contribute to our public repository, additional access is granted through Write and Admin roles. (There are other defined roles that aren't often used.)

Every member of the Docs team is granted the Admin role, which grants full access to the repository. Other New relic contributors are given the Write role, which permits assigning users and opening and closing pull requests.

To review the current access settings, go to the docs-website repo, then go to Settings > Collaborators and teams or Team and member roles.