-
Notifications
You must be signed in to change notification settings - Fork 118
feat: Update issue templates & process docs #1287
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
This commit updates the issue templates into the repository, converting them from plain Markdown templates to interactive forms. It also updates the process documentation, re-organising them into topic groups and adding guidance on the level of desired detail for requests.
✅ Deploy Preview will be available once build job completes!
|
|
||
- If an issue involves changing a common noun, it may affect other work priorities | ||
- If an issue is related to an upcoming release, it might need attention soon | ||
- If an issue leaves users in an operable state, it requires intervention immediately |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I read "operable state" and I think "Oh, the software is still working with these docs, we can address the issue later"
- If an issue leaves users in an operable state, it requires intervention immediately | |
- If an issue leaves users with broken software, it requires intervention immediately |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Inoperable?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"If an issue leaves users in an inoperable state," or the system/product/whatever? I'm guessing the users are probably ok, operable.
Maybe: If the system or product breaks and users can’t do their work, the issue should be fixed right away.
That breaks the "If an issue ..." pattern, but that might be repetive.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
General comment:
IMO, it'd help focus the person who creates the issue to write this in the 2nd person / active voice
It's written from the perspective of a user, whose priorities are often different from your own. | ||
|
||
The users for each story may map to specific user personas dependent on the required content design complexity. | ||
|
||
A user persona reflects a broad set of demographic criteria, representing a type of person who may have different levels of experience, domain knowledge or priorities. | ||
|
||
Acceptance criteria are used to determine whether or not the need identified as part of a user story is fulfilled. | ||
|
||
Much like the user story, it is the user perspective that defines how acceptance criteria are written. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's written from the perspective of a user, whose priorities are often different from your own. | |
The users for each story may map to specific user personas dependent on the required content design complexity. | |
A user persona reflects a broad set of demographic criteria, representing a type of person who may have different levels of experience, domain knowledge or priorities. | |
Acceptance criteria are used to determine whether or not the need identified as part of a user story is fulfilled. | |
Much like the user story, it is the user perspective that defines how acceptance criteria are written. | |
Write user stories from the user’s perspective. Their goals may not match yours. | |
For each user story, think about which user persona it maps to. A persona represents a type of person with shared traits like experience level, domain knowledge, or goals. A user story written for a DevOps persona will look different from one written for SecOps. | |
Use acceptance criteria to define what needs to be true for the story to be complete and the user’s need to be met. | |
Just like user stories, write acceptance criteria from the user’s point of view. Focus on what they expect, not what you want to build. |
Taking a stab at second-person voice, speaking directly to the reader completing the form. Also, lowered the reading level from 13 --> 7 (style guide recommends 8-9).
Proposed changes
This commit updates the issue templates into the repository, converting them from plain Markdown templates to interactive forms. It also updates the process documentation, re-organising them into topic groups and adding guidance on the level of desired detail for requests.
Checklist
Before sharing this pull request, I completed the following checklist:
Footnotes
Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content. ↩