Skip to content

Conversation

ADubhlaoich
Copy link
Contributor

@ADubhlaoich ADubhlaoich commented Oct 10, 2025

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

  1. Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content.

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.
@github-actions github-actions bot added tooling Back end, repository, Hugo, and all things not related to content process documentation Documentation related to how the repository or documention itself is managed. labels Oct 10, 2025
Copy link

Deploy Preview will be available once build job completes!

Name Link
😎 Deploy Preview https://frontdoor-test-docs.nginx.com/previews/docs/1287/


- 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
Copy link
Contributor

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"

Suggested change
- 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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inoperable?

Copy link
Contributor

@travisamartin travisamartin Oct 11, 2025

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.

Copy link
Contributor

@mjang mjang Oct 10, 2025

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

Comment on lines +17 to +25
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.
Copy link
Contributor

@travisamartin travisamartin Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

process documentation Documentation related to how the repository or documention itself is managed. tooling Back end, repository, Hugo, and all things not related to content

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants