Merge pull request #3380 from newrelic/pm-handbook

Create agile handbook
newrelic · Oct 14, 2021 · 6ba5d3b · 6ba5d3b
2 parents e722112 + 8cabc4a
commit 6ba5d3b
Show file tree

Hide file tree

Showing 18 changed files with 1,367 additions and 4 deletions.
diff --git a/src/content/docs/agile-handbook/appendices/backlog-review.mdx b/src/content/docs/agile-handbook/appendices/backlog-review.mdx
@@ -0,0 +1,53 @@
+---
+title: "Backlog review"
+template: basicDoc
+topics:
+  - Docs agile handbook
+---
+About once a quarter, the Docs team reviews our entire  backlog in Jira and GitHub. This ensures that we actually know what's in there, and that we're bubbling up the right stories from the backlog into upcoming sprints.
+
+## 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? 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?
+
+## Who reviews the backlog [#review_who]
+
+Sometimes we'll involve the whole team in a backlog review; other times, just the managers will handle the review. 
+
+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. 
+
+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
+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.
+5. Add a label to the issue once you're done with your review.
+    - Use this format: `year_month_backlog_review`. For example: `2021_october_backlog_review`. 
+    - This helps keep track of which issues you've reviewed on this round of backlog review
+    - It's also a useful nudge for future round of review: If an issue has more than one or two review labels, you should probably close it.
+
+<ButtonGroup>
+  <ButtonLink
+  role="button"
+  to="/docs/agile-handbook/appendices/project-scoping-cheatsheet/"
+  variant="secondary"
+  >
+  ← Appendix: Project scoping cheatsheet
+  </ButtonLink>
+</ButtonGroup>
+
+## For more help
+
+We welcome thoughts or questions on our handbook! The easiest way to get in touch is to [file a GitHub issue](https://github.com/newrelic/docs-website/issues/new/choose).
diff --git a/src/content/docs/agile-handbook/appendices/project-scoping-cheatsheet.mdx b/src/content/docs/agile-handbook/appendices/project-scoping-cheatsheet.mdx
@@ -0,0 +1,72 @@
+---
+title: "Project scoping cheatsheet"
+template: basicDoc
+topics:
+  - Docs agile handbook
+---
+We use this cheatsheet to help us scope projects in a consistent way.
+
+## What is this [#what_is_this]
+
++ What's the elevator pitch for the feature? What's the user value?
++ What are the most exciting tasks/stories we can tell for this feature?
++ Who is the primary audience?
++ Any docs deliverables you already have in mind?
+
+## Dates [#dates]
+
++ What are you working on right now?
++ When does this "release" (private beta, public beta, GA, etc.)?
++ If private beta, how many customers and do they need docs?
+
+## Scope [#scope]
+
++ Who will write first drafts?
++ Do you need any templates?
++ Does this need a liaison?
+
+## Resources [#resources]
+
++ Is there a test account/is this in staging?
++ Are there mockups or other resources?
++ Do you have any other collateral to share?
+
+## People [#people]
+
++ Who is the primary reviewer (and backups)?
++ Who is product manager?
++ Who is lead dev?
++ Who is the designer?
++ Who is program manager?
++ Who is the researcher? Are we doing any user research?
++ Who is the PMM?
++ Who is the support point person?
+
+## Before meeting ends [#before_meeting_ends]
+
++ Who is writing?
++ When is it due?
++ Do we need tickets?
++ Who is following up with who?
+
+<ButtonGroup>
+  <ButtonLink
+  role="button"
+  to="/docs/agile-handbook/appendices/ticket-best-practices/"
+  variant="secondary"
+  >
+  ← Appendix: Ticket best practices
+  </ButtonLink>
+
+  <ButtonLink
+  role="button"
+  to="/docs/agile-handbook/appendices/backlog-review/"
+  variant="secondary"
+  >
+  Appendix: Backlog review →
+  </ButtonLink>
+</ButtonGroup>
+
+## For more help
+
+We welcome thoughts or questions on our handbook! The easiest way to get in touch is to [file a GitHub issue](https://github.com/newrelic/docs-website/issues/new/choose).
diff --git a/src/content/docs/agile-handbook/appendices/ticket-best-practices.mdx b/src/content/docs/agile-handbook/appendices/ticket-best-practices.mdx
@@ -0,0 +1,162 @@
+---
+title: "Ticket best practices: How to write a sprint-ready Jira"
+template: basicDoc
+topics:
+  - Docs agile handbook
+---
+
+Jira, a project management tool made by Atlassian, is how we manage our projects and understand the work we are doing and have done.
+
+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 a template that helps create a good ticket.
+</Callout>
+
+## Why do we use Jira? [#why_jira]
+
+We create tickets to record work-to-be done for a project, scope new work, share information for any writer to complete a story, forecast our output and to estimate project timelines, and have a record of work done.
+
+In other words, Jira has a role at every point in a project:
+
+<table>
+    <tbody>
+    <tr>
+      <td>
+        Before a project
+      </td>
+      <td>
+        Scoping, syncing on expectations, giving tech writer instructions
+      </td>
+    </tr>
+    <tr>
+      <td>
+        During a project
+      </td>
+      <td>
+        Keeps team and management posted about project; allows for hand-offs and swarming
+      </td>
+    </tr>
+    <tr>
+      <td>
+        After a project
+      </td>
+      <td>
+        Understand what work we did, and helps researching on future projects
+      </td>
+    </tr>
+    </tbody>
+</table>
+
+## 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 a couple hours is a good candidate for a ticket. 
+
+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 (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 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.)
+
+## Add Jira context to PRs and commits [#links_to_github]
+
+When you edit the site, include the Jira issue key (DOC-1234, for example) in your pull request title and/or commit summary. That makes it easier for other writers to connect the dots later if we're trying to figure out why something changed or who knows about a particular subject.
+
+## Checklist for writing a good ticket [#jira_checklist]
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        Helpful title
+      </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`.
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Action items
+      </td>
+      <td>
+        - An action item list describing the work to be done
+        - What docs are affected
+        - 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
+        - Anyone who should be notified when a doc is published
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Proper sizing
+      </td>
+      <td>
+        - Story is scoped to the smallest reasonable size
+        - Can be completed within a 2 week sprint
+        - Delivers incremental value
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Dates
+      </td>
+      <td>
+        - Publication date or due date
+        - Dates for other key events (betas, limited releases, etc.)
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Resources and people
+      </td>
+      <td>
+        - People, including last names and roles 
+        - List of related or affected docs
+        - Other internal and external resources
+        - Related issues
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Labels and fields
+      </td>
+      <td>
+        - Jira tickets: Component, Product Group, and Priority
+        - GitHub issues: `from_`, `pg_`, and `content` labels
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<ButtonGroup>
+  <ButtonLink
+  role="button"
+  to="/docs/agile-handbook/heroing/managing-the-github-boards/"
+  variant="secondary"
+  >
+  ← Managing the GitHub boards
+  </ButtonLink>
+
+  <ButtonLink
+  role="button"
+  to="/docs/agile-handbook/appendices/project-scoping-cheatsheet/"
+  variant="secondary"
+  >
+  Appendix: Project scoping cheatsheet →
+  </ButtonLink>
+</ButtonGroup>
+
+## For more help
+
+We welcome thoughts or questions on our handbook! The easiest way to get in touch is to [file a GitHub issue](https://github.com/newrelic/docs-website/issues/new/choose).