Skip to content

Commit

Permalink
style(agile handbook): Finish copyedit and consistency edit
Browse files Browse the repository at this point in the history
  • Loading branch information
austin-schaefer committed Oct 8, 2021
1 parent b35e8a8 commit 71d5774
Show file tree
Hide file tree
Showing 4 changed files with 34 additions and 36 deletions.
6 changes: 3 additions & 3 deletions src/content/docs/agile-handbook/appendices/backlog-review.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ About once a quarter, the Docs team reviews our entire backlog in Jira and GitH
## Goals of backlog review [#review_goals]

- **Fix easy issues**: If you can fix something quickly, just do it.
- **Find broken windows**: What are the small (or big!) broken windows lurking in our backlog? Find issues you want to champion for Input Queue.
- **Find broken windows**: What are the small (or big!) broken windows lurking in our backlog? What should we consider bubbling up into a future sprint?
- **Identify gaps in the backlog**: Discover important issues that are not at all covered in the backlog.
- **Clear out cruft**: Find duplicate issues, things we'll never fix, or issues that are just no longer relevant.
- **Check labels and fields**: Is the ticket assigned a correct priority score? Do we have the correct labels for other fields?
Expand All @@ -20,16 +20,16 @@ Sometimes we'll involve the whole team in a backlog review; other times, just th

The most useful time to involve the whole team is when we're onboarding a new writer: Talking through issues promotes a lot of knowledge-sharing about the product, docs, stakeholders, and how to write a good ticket.

Most other times, we'll just assign the review to the managers. This saves time, and it also tends to make it easier to close out issues (since our managers are our product owners). If we don't involve the whole team, we'll prepare a spreadsheet of which issues we closed and list writers who might care so they can weigh in on whether the issue should have stayed open.
Otherwise, we'll usually assign the review to the managers. This saves time, and it also tends to make it easier to close out issues (since our managers [are also our product owners](/docs/agile-handbook/key-concepts/agile-roles/#team_managers)). If we don't involve the whole team, we'll prepare a spreadsheet of which issues we closed and list writers who might care so they can weigh in on whether the issue should have stayed open.

## What to look for in a backlog review [#review_checklist]

When you review an issue, perform the following checks:

1. Check if the issue can be closed:
- It's already resolved, or you can't reproduce the issue
- It's old, and we have little evidence anyone cares
- It's not important enough to fix
- It's very old, and we have little evidence anyone cares
2. If the issue doesn't have a clear goal/task, try to discover one (but don't feel obligated to rewrite the whole issue).
3. Add context and update as-needed.
4. Review fields and labels and ensure they're accurate.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Jira, a project management tool made by Atlassian, is how we manage our projects
Jira tickets may seem at first to be simple to-do lists that we use to know what things to do for a project. But they are much more important than that.

<Callout variant="tip">
For Relics: Use the [docs.newrelic.com/jira](https://docs.newrelic.com/jira) template when you create a ticket! It'll automatically pre-fill your ticket with most of the necessary info to create a good ticket.
For Relics: Use the [docs.newrelic.com/jira](https://docs.newrelic.com/jira) template when you create a ticket! It'll automatically pre-fill your ticket with a template that helps create a good ticket.
</Callout>

## Why do we use Jira? [#why_jira]
Expand Down Expand Up @@ -50,19 +50,19 @@ In other words, Jira has a role at every point in a project:

## What work needs a ticket?

There aren't hard-and-fast rules about what work needs a Jira ticket and what doesn't. A good shorthand is that any project that takes more than an hour is a good candidate for a ticket.
There aren't hard-and-fast rules about what work needs a Jira ticket and what doesn't. A good shorthand is that any project that takes more than a couple hours is a good candidate for a ticket.

However, the goal of creating tickets is not to track writer time in detail (see section above). So many kinds of work (meeting times, ongoing minor [liaison tasks](/docs/agile-handbook/sprint-mechanics/liaisonships/), [hero work](/docs/agile-handbook/heroing/what-is-a-hero/)) generally do not need to go into Jira.
However, the goal of creating tickets is not to track writer time in detail. So many kinds of work (meetings, ongoing minor [liaison tasks](/docs/agile-handbook/sprint-mechanics/liaisonships/), [hero work](/docs/agile-handbook/heroing/what-is-a-hero/)) generally do not need to go into Jira.

## Keeping tickets up-to-date [#lottery_factor]

In general, you should write your tickets [as though you might win the lottery tomorrow](https://en.wikipedia.org/wiki/Bus_factor). That is, someone should be able to read your ticket and figure out within about ten minutes what the status is and what the next step is. This makes it easy for us to take vacations, pass work off to another docs writer if needed, and escalate blockers.
In general, you should write your tickets as though you might win the lottery tomorrow (a principle known as lottery factor or [bus factor](https://en.wikipedia.org/wiki/Bus_factor). In practice, someone should be able to read your ticket and figure out within about ten minutes what the status is and what the next step is. This makes it easy for us to take vacations, pass work off to another docs writer if needed, and escalate blockers.

These things help with lottery factor:

- Update the Action Item list as you complete tasks and add or remove scope.
- When you move a ticket to Blocked, include a note explaining the change in status.
- When closing a ticket, give a summary of the work done and any relevant thoughts you have on the work and potential related issues.
- When you close a ticket, give a summary of the work done and any relevant thoughts you have on the work and potential related issues.
- Update the Timeline, People, and Resources sections as the project evolves.
- Add important conversations (emails or Slack convos from SMEs) that give important context for the work done. (Note: It's a good idea to ask permission before doing this, because some people might not like their informal words placed in a public place.)

Expand All @@ -80,7 +80,7 @@ When you edit the site, include the Jira issue key (DOC-1234, for example) in yo
</td>
<td>
- A ticket name should be easy to find via search, understand the work at a glance, mention the product or feature, and describe the goal or issue.
- Examples of good ticket titles: "Browser API: Update custom attribute-related docs" or "Distributed tracing: Add more detail about CAT relationship"
- Examples of good ticket titles: `Browser API: Update custom attribute-related docs` or `Distributed tracing: Add more detail about CAT relationship`.
</td>
</tr>
<tr>
Expand All @@ -90,7 +90,7 @@ When you edit the site, include the Jira issue key (DOC-1234, for example) in yo
<td>
- An action item list describing the work to be done
- What docs are affected
- Links to drafts is applicable
- Links to pull requests, Google Docs drafts, etc.
- How substantial the writing work is in each doc
- How the resulting work should be structured
- Whether or not a peer edit is needed
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,16 @@ The [Docs pull requests and Issues](https://github.com/newrelic/docs-website/pro

Assignee and Reviewer have different meanings:

- **Assignee** means you "own" the pull request or issue and are getting it into a merge-ready state. If you are no longer owning a given pull request or issue, take your name off as assignee.
- **Assignee** means you own the pull request or issue and are getting it into a merge-ready state. If you are no longer owning a given pull request or issue, take your name off as assignee.
- **Reviewer** means you are actively reviewing a pull request. If it's a pull request from outside the docs team, the reviewer is also responsible for merging the pull request into `develop`. If you're reviewing a pull request from a fellow docs writer, add your comments and mark the pull request as **Approved**, then move it to **Waiting on TW to merge**.

## Drafts [#column_drafts]
## Drafts column [#column_drafts]

These issues and pull requests are in a draft state. Do not merge until their owner moves them out of the lane. This lane should _only_ be for draft pull requests. Do not "hold" pull requests or issues here.
These issues and pull requests are in a draft state. Do not merge until their owner moves them out of the column. This column should _only_ be for draft pull requests. Do not "hold" pull requests or issues here.

The Hero should look at this lane multiple times per day in case a pull request has been marked ready for review. Move any ready-for-review pull requests into the correct lane.
The Hero should look at this column multiple times per day in case a pull request has been marked ready for review. Move any ready-for-review pull requests into the correct column.

## Hero to triage [#column_hero-to-triage]
## Hero to triage column [#column_hero-to-triage]

New issues and pull requests flow into this column automatically. As hero, you need to triage each one:

Expand Down Expand Up @@ -76,36 +76,34 @@ New issues and pull requests flow into this column automatically. As hero, you n
</tr>
</tbody>
</table>
3. Give the ticket an assignee (most likely the Hero themselves).
3. Give the ticket an assignee (most likely you).
4. Move the ticket to the appropriate column.

## Hero: To do [#column_hero-to-do]
## Hero: To do column [#column_hero-to-do]

On the basis of the triage work, the GH Hero has determined that this is appropriate in scope and range to be dealt with while Heroing, but hasn't started work yet.
Work that the GitHub has triaged, but hasn't started working on yet. Tickets in this column need to have an assignee.

Tickets in this column need to have an assignee.
## In progress/being reviewed column [#column_in-progress]

## In progress/being reviewed [#column_in-progress]
Work is underway on this issue or pull request. For example, reviewing pull requests from outside the team, doing a peer edit, investigating a GitHub issue. The person doing the work should make themselves the assignee as soon as they move the pull request or issue into this column to prevent others from duplicating work.

Work is underway on this issue or pull request. This includes but is not limited to reviewing incoming pull requests from outside the team, performing a peer review/peer edit, or doing a simple pull request review for another tech writer. The person doing the work should make themselves the assignee as soon as they move the pull request or issue into this column to prevent others from duplicating work.

## Writer needs PR review [#column_writer-pr-review]
## Writer needs PR review column [#column_writer-pr-review]

Exactly what it says. Typically, the writer who submitted the pull request will move it to this column.

A pull request review means reviewing for basic stuff like is it looking okay on preview, are there broken links or images that don't render, and are there any obvious errors in the .mdx content shown in the diff. When a pull request review is complete, this should be marked approved in GH.
A pull request review means reviewing for basic stuff like is it rendering correctly, are there typos or wording issues, and are there any obvious errors in the .mdx content shown in the diff. Once you've reviewed the pull request, mark it approved in the GitHub review UI, and move it to the **Waiting on TW to merge** column.

## Writer needs peer edit [#column_writer-peer-edit]
## Writer needs peer edit column [#column_writer-peer-edit]

Also exactly what it says. As with pull request review column, the writer who submitted the pull request will drag to this column.

This includes all the stuff in a pull request review plus an actual peer edit. If the person requests changes the pull request should not be marked approved. If there are some suggestions, but none that need to be acted on before merging, it's okay to mark the pull request approved and leave further updates at the discretion of the writer who will be responsible for eventually merging the pull request.
This includes all the stuff in a pull request review plus an actual peer edit. Once you've reviewed the pull request and left your feedback in the GitHub review UI, mark it **Approved** and move it to the **Waiting on TW to merge** column. From there, the author of pull request is responsible for reviewing the feedback and updating it before merging. If you find significant issues (inaccuracies, bad formatting, build issues), don't mark it **Approved**.

## Waiting on SME/blocked [#column_waiting-on-sme-blocked]
## Waiting on SME/blocked column [#column_waiting-on-sme-blocked]

Blocked until something else happens. Usually this means it's waiting on answers/verification from SME or the person who submitted the pull request.
Blocked until something else happens. Usually this means it's waiting on answers or approval from the SME or the person who submitted the pull request.

## Waiting on TW to merge [#column_waiting-on-tw-merge]
## Waiting on TW to merge column [#column_waiting-on-tw-merge]

When a docs writer creates a pull request, it's their responsibility to merge it into `develop` at the appropriate time. After a reviewer is done with their pull reuqest review or peer edit, they move it into this column so the original writer can merge when ready.

Expand Down

0 comments on commit 71d5774

Please sign in to comment.