Story pointing
Not all issues are created equal. To help plan our anticipated workloads for each train and distribute issues efficiently, we assign story points to issues that provide an estimate for how difficult and time-intensive each issue is. While assigning story points is a subjective process, there are still some guidelines you can follow.
Dashboard
Use the ACM Documentation Dashboard to see an overview of issues and story points. You can use the dashboard to quickly assign story points to multiple issues. You can also assign story points to issues by selecting individual issues on the Kanban board.
Note: Story points are only visible at a glance on the dashboard.
General rules
- The range of points consists of integers from
1to10, with1being āI can knock this out in 5 minutesā and10being āIām sending UNSUBSQUIRREL as reply all to memo-listā. Do not use fractions or integers above 10. - Estimate points when triaging issues, but feel free to change them any time during your work process, including after you have already closed the issue. Add a comment when to explain why the points changed.
- With all issues, including
1point issues, itās important to take a step back and consider the purpose and necessity of the change.
Rubrics
Consider the following rubrics when assigning story points to Jira issues:
| Rubric | Description |
|---|---|
| Difficulty | How complex an issue is and how many additional factors you have to consider. |
| Research | How much new information you need to seek out and learn to understand or solve the issue. |
| Length | How many new files, topics, or individual lines it takes to solve the issue. |
| Review | Who and how many people need to review your solution before merging. |
| Product knowledge | How much product knowledge and planning knowledge is required. |
| Writing time | How long it takes to write the content. |
Ā
Important:
- Rubrics are guidelines and can vary based on your experience, delays in builds, communication, unknown complexities, and other things out of our control. Itās important to use your judgement, but to be as objective and honest as possible when choosing or changing your story.
- New features always require dev, QE, and a peer review, regardless of their story points. If QE review is not possible, you can substitute it with a second dev review.
Ā
1 point
The most basic type of issue usually consisting of fixing typos, links, or indentations. The information provided in the issue is always sufficient to solve the issue quickly, with no additional research or communication. A review not typically needed when fixing typos or links, but usually is required when editing code samples, even for simple indentation fixes.
| Rubric | 1 point description |
|---|---|
| Difficulty | Very easy. Diff is clear without additional work. |
| Research | None. |
| Length | A single or a few characters added/changed in one file. A phrase at most. |
| Review | None if only fixing typos or links (peer review still recommended). Dev and peer review required for all other cases. |
| Product knowledge | Little product knowledge is needed. |
| Writing time | A few minutes. |
Ā
2 points
A simple issue that requires little additional work to understand the diff. These are often straightforward new known issues being requested by developers, complete with a full and mostly edited draft. You might need to make minor style adjustments, but the information is complete and to use in your workflow.
| Rubric | 2 points description |
|---|---|
| Difficulty | Easy. Might require minimal style and formatting considerations. |
| Research | Minimal (in the form of verification) to none. |
| Length | One or two paragraphs in one file. |
| Review | Dev and peer review. |
| Product knowledge | Little product knowledge is needed. |
| Writing time | About an hour. |
Ā
3 points
A relatively simple issue that requires minimal additional research and editing. Might include more involved new known issues, a request for clarifying steps in the docs, or adding new information in an existing topic that requires additional considerations, such as placement in the docs or verification from additional sources.
| Rubric | 3 points description |
|---|---|
| Difficulty | Some rewriting and editing is required. |
| Research | You might need to reach out for verification or have short discussions about the implementation. |
| Length | One or a few paragraphs in one or more files. |
| Review | Dev and peer review. |
| Product knowledge | More product awareness is needed than previous points. |
| Writing time | Up to a day when additional communication is needed. |
Ā
4 points
4 point issues tend to be very common and diverse, ranging from requests for new topics to restructuring of existing content. While difficult to generalize, you can expect more work and investment across all rubrics compared to 3 point issues, especially when it comes to architecture considerations, research, and communication with SMEs. You can also expect an extended review process that requires you to adjust your pull request based on feedback multiple times.
| Rubric | 4 points description |
|---|---|
| Difficulty | Includes drafting new content or adapting drafts that require verification, discussion, and review from SMEs. |
| Research | You might need to research a topic and learn basic new concepts. |
| Length | Varies, but often requires several lines across multiple files. |
| Review | Dev and peer review. |
| Product knowledge | More product and ACM team awareness is expected for this issue. |
| Writing time | A day or more, depending on how much communication and research is needed. |
Ā
5 points
A somewhat difficult issue that requires you to research topics, reach out to SMEs, and go through an extended review process. Can include anything from documenting new features to overhauling existing sections of documentation. Information provided usually needs to be expanded, verified, and rewritten, all while considering the doc architecture, style, formatting, and user needs.
| Rubric | 5 points description |
|---|---|
| Difficulty | You need to author new topics and content based on multiple sources. Includes research and communication with multiple SMEs. Consider style, formatting, user needs, and, to some extent, the architecture of the doc. |
| Research | Reaching out to SMEs, learning new technical and product concepts, and becoming familiar with the architecture of the doc section affected. |
| Length | Varies, but often requires several topics across multiple files. |
| Review | Dev, QE, and peer review. |
| Product knowledge | Product awareness and knowledge is required. |
| Writing time | A day or more, depending on how much communication and research is needed. |
Ā
6 points
A difficult issue similar to 5 point issues, but with even more investment required across all rubrics.
| Rubric | 6 points description |
|---|---|
| Difficulty | You need to author new topics and content based on multiple sources. Includes research, communication with multiple SMEs, and, sometimes, meetings for discussion. You need to consider the doc architecture, style, formatting, and user needs. |
| Research | Reaching out to SMEs, learning new technical and product concepts, and becoming familiar with the architecture of the doc section affected. Meetings might be helpful. |
| Length | Varies, but often requires several topics across multiple files. |
| Review | Dev, QE, and peer review. |
| Product knowledge | Product awareness and knowledge is required. |
| Writing time | Multiple days, depending on how much communication and research is needed. |
Ā
7 points
The first level of issue difficulty that requires more product/component knowledge, strong awareness of doc architecture, and release planning. The issue might provide a general request with some details or limited drafts, but doesnāt provide clear directions about how to accomplish the goal. It is up to you to research, plan, and write a solution to solve the issue, all while considering architecture, the user story, style, and formatting. You need to meet or consult with multiple SMEs and, potentially, team leaders.
| Rubric | 7 points description |
|---|---|
| Difficulty | Complex authoring of new content based on limited available information. You need to have strong awareness of the doc architecture to make the right decisions. |
| Research | Intensive research required to understand the issue and topic. You also need to gather complex information through various channels and verify it. Meetings with SMEs are likely necessary. |
| Length | Varies, but can require some input in up to a dozen files. |
| Review | Dev, QE, and peer review. PM review is encouraged. |
| Product knowledge | Product awareness, knowledge, and release planning is required. |
| Writing time | Can be done within a train. |
Ā
8 points
A complex issue similar to 7 point issues, but with even more investment required across all rubrics.
| Rubric | 8 points description |
|---|---|
| Difficulty | Complex authoring of new content based on limited available information. You need to have strong awareness of the doc architecture to make the right decisions. |
| Research | Intensive research required to understand the issue and topic. You also need to gather complex information through various channels and verify it. Meetings with SMEs and team leaders are necessary. |
| Length | Varies, but can require some input in up to a dozen files. |
| Review | Dev, QE, and peer review. PM review is encouraged. |
| Product knowledge | Product awareness, knowledge, and release planning is required. |
| Writing time | Might require more than one train. |
Ā
9 points
A highly complex but rare issue characterized by the lack of a clear, stable direction. As content and features are still in the planning phase, expect frequent changes that you need to deal with, in addition to the difficulties of 7 and 8 point issues.
| Rubric | 9 points description |
|---|---|
| Difficulty | Complex authoring of new content that is still being decided. Expect additional effort when dealing with frequent changes. You need to have strong awareness of the doc architecture to make the right decisions. |
| Research | Requires lengthy research to understand the content and explain it. Often requires putting together information from multiple sources. |
| Length | Varies, but can require major input in over a dozen files. |
| Review | Dev, QE, PM, and peer review. |
| Product knowledge | Product awareness, knowledge, and release planning is required. |
| Writing time | One release or less. |
Ā
10 points
An extremely complex issue that requires massive work on all fronts and input from multiple parties. Can require an epic and might consist of multiple smaller issues. Several meetings and extensive review are required.
| Rubric | 10 points description |
|---|---|
| Difficulty | Complex authoring, editing, and decision-making on content that might not exist yet. You need mastery of the doc architecture to make the right decisions. |
| Research | Extensive research on all fronts, including style, technical concepts, and customer needs. Information comes from a multitude of sources. Recurring meetings with product managers, SMEs, developers, and team leaders are required. |
| Length | New book or multiple books, with in put in dozens or even hundreds of files. |
| Review | Multiple dev, QE, PM, and peer reviews. |
| Product knowledge | Product awareness, knowledge, and release planning is required. |
| Writing time | Might require one or multiple releases. |
Ā