Tech doc writers (TW) are responsible for the docs. We write and edit the docs and exchange peer edits, maintain our backlog, and hero. To make it all happen, we use our Docs Team GitHub board to manage filed issues and pull requests (PRs).
GitHub tracks every stage of an issue or pull request's life cycle, including the people moving things along.
Because the Docs team invite anyone to file an issue or create a pull request through GitHub, we strongly recommend verifying a filer's relationship to the New Relic GitHub organization. If you're uncertain if a contributor is a Relic, a good trick is to check if they're a member of the New Relic GitHub org. Generally, we recommend assuming a filer is external until proven otherwise.
Who's who of an issue or PR:
- Creator: This is the person who opens the issue or PR. The creator could be someone on the Docs team, another Relic, or an external user. You'll label the issue or PR differently depending on who created it.
- Assignee: This is the person who takes responsibility for an issue or PR and sees it through to publication. The Hero will assign non-TW issues and PRs to themselves, or they can take over an issue or PR from another writer.
- Reviewer: This is the person who provides a peer edit of your code or document and then approves the changes. This is not necessarily the person responsible for that area or responsible for merging the commit. You can assign up to 100 reviewers to a given issue.
The docs board has the following columns:
A draft is a way to open a PR while indicating that the work is still in progress and not necessarily ready to merge immediately. You can't merge a Draft PR directly. Instead, you must move it out of draft status first.
When you see a draft PR (especially from outside the team!), treat it as though it's a working draft, and reach out to the creator to discuss.
Read more on GitHub's drafts.
Hero to triage
This is the column where new PRs and GitHub issues land on the board. After inspecting and labeling them, the Hero drags them to the appropriate column.
If a PR or issue is labeled
Use this column for "What's new" posts or other time-sensitive issues that you want the hero to watch. Insert the projected publication date in the title so everyone can see it.
Drag PRs to this column when you are working on them. Make sure your face is on the PRs so other writers don’t mistakenly work on them.
This is where you insert your PRs when you are ready to get a review. This is for all types of reviews: everything from minor fixes to complicated Jiras.
When you pick up a PR from Needs review:
Waiting on SME/Blocked
For PRs that are blocked by need for SME info or confirmation (for example, as Hero you are waiting on an answer from the person who sent in a Hero pull request).
Waiting on TW to merge
All reviews are complete. The TW who created the PR (or who is assigned the issue) needs to merge this work into develop.
As a Hero, make sure you attend to the following throughout your day:
- Check in with the previous Hero at the start of your day (especially on Monday at the start of the week). Don’t forget to sync with the BCN Hero if necessary.
- Watch for incoming PRs in #docs_deploys, and check everything in the Needs triage column. Drag cards from that column to the appropriate column.
Everyone on the team helps keep things moving:
- All writers should keep an eye on the Needs review column. If a PR doesn't have a reviewer, you can pick it up.
- When you are ready for any type of review (simple or complex), move your PR into Needs review.
- Be sure to move PRs that are blocked by SMEs to Waiting on SME/Blocked.
- Check Waiting on TW to merge to see if your PR feedback is finished.
- After you incorporate peer feedback, merge the PR, and remove it from the board.
- Don't link to anything non-public from a public place.
- You can reference Jira tickets, but reference tickets by issue key (
DOC-1234is ok) rather than a link (
- Don't mention traffic or usage numbers publicly.
- Don't reference internal people by name. If they have a GH account, @mention their GH handle. If they don't, talk instead about teams ("talk to a browser team engineer" or "Support Engineer") rather than people.
- You can mention the #help-documentation channel and hero.
The Hero currently merges at 9 AM (morning), 12 PM (noon), and 3 PM (evening) Pacific. We merge release branches into main to avoid interuptions when someone merges into develop during a release. To learn more about this workflow, see the gitflow documentation in Atlassian.
It's important to create a new release branch off of the develop branch. Before you create a new branch, make sure you're on develop.
To start a release:
- Create a branch of
developusing Github Desktop by clicking Current Branch in the top header, New Branch in the dropdown, then selecting Develop.
- Name the branch with this pattern:
daily-release/mm-dd-yy-morning/noon/evening. For example, a daily release happening at 9am on October 27, 2021 would follow this style:
- To push your changes, in GitHub Desktop click Push Origin.
- Create a pull request into main from your new daily release branch by clicking Create Pull Request. This will open a pull request screen on github.com. Pull requests default to merging into develop, so select main as the
basebranch in the left side of the page and then click
Submit Pull Request.
- Wait until all the checks complete, and then merge the pull request.
All branches that follow the
daily-release/mm-dd-yy-morning pattern are protected branches. Only admins can delete them.
We apply labels to issues so we can better triage and track the health of our backlog:
content: All issues use this label.
contentindicates the issue is content-related rather than a design or engineering issue.
pg_*: Docs team will always use this label to indicate product group. For full definitions, see the "Doc Jira and GitHub fields" doc in the internal team Google Drive.
- Indicate who created the issue:
from_internal: A Relic created it.
from_external: A non-Relic opened the issue in the repo OR the issue came in through #customer-feedback process.
from_tw: One of us created it (unless we were passing along #customer-feedback).
docs-issue-candidate: Issues that are too large in scope for the docs team to handle without product team expertise. This label alerts the docs issues team to migrate these issues into the customer feedback channel where they will be triaged and sent to product teams.
Jira’d: Issues that have a corresponding Jira ticket. Make sure you leave the Jira number in the comments of the issue (for example, DOC-1234).
Every pull request needs these labels so we can see where our contributions come from:
content: Always add, this indicates the PR is content-related rather than design or engineering.
- Indicate who created the pull request:
from_internal: A Relic created it.
from_external: A user opened it in the repo OR it came in through #customer-feedback process.
from_tw: One of us created it (unless we were passing along #customer-feedback). If the PR fixes an external issue, label it as
from_twsince the work was done by a tech writer.
There's no hard and fast rule in choosing good candidates for docs issues. They could be anything too difficult for a docs hero to chase down, or anything that could benefit from deep engineering expertise. Some examples are code examples, requirements sections, and NRQL queries.
Ultimately, docs issues helps the docs team collaborate with product teams to solve documentation and product issues. It lets us leverage product team expertise to solve as many issues as we can, regarldess of who filed them.
The life cycle of a viable issues candidate looks something like this:
- Someone files an issue through GitHub for the GitHub hero to evaluate it as a potential candidate.
- The hero adds the
docs-issue-candidatelabel. After, the hero archives the issue.
- Every week, a designated docs team member assesses all issues with the
- If approved, the
docs-issue-candidatelabel is changed to a
docs-issuelabel. We then migrate the issue into the customer feedback Jira project.
- The new jiras are triaged by PMs, then funneled to the correct project team.
- The PM will give the ticket to an assignee, who will close it once complete.