RFC [process]: SIG docs-community assignment during triage

[sptramer]

Summary

Prior to June 2022, there was a regular meeting owned by sig-release which was for the assignment of SIGs to issues which were recently filed, in order to sort them per-SIG for triage. This process has now been deprecated, meaning that each SIG is responsible for triaging the O3DE repo on their own, examining needs-sig issues and determining if they own it (and who the ultimate owner may be.) One consequence of removing this meeting is that downstream SIGs such as UI/UX and Docs-Community is that there is no longer a global triage for those SIGs to participate in, and instead individual SIGs will be required to identify when a downstream SIG will be affected by their work.

As a consequence, we need formal guidance for "when do you apply the sig/docs-community label?" during triage sessions. Without early engagement of documentation for certain features or product issues,

What is the motivation for this suggestion?

SIG assignment triage is ending, and being delegated as part of the responsibility of individual SIG triage sessions.

Suggestion design description

The following is a draft for discussion of the guidelines which would be given to SIGs for assigning the sig/docs-community label or assigning docs-community reviewers to pull requests.

When should SIG Docs-Community be informed of an issue?

There are only a few incoming issues where SIG Docs-Community needs to be engaged:

• If an issue is kind/bug, Docs-Community does not need to be engaged, unless the bug resolved has a written workaround in official documentation. A user fixing a consequential enough bug that previously required a workaround is expected to follow the Impactful Change requirements for documentation (TBD) to evaluate their bug fix against the documentation.
• Issues involving deprecation must always include sig/docs-community so that we can correctly identify any deprecated documentation outside of API reference.
• If an issue was mistakenly filed against the o3de repo and relates strictly to documentation, it should be moved to the o3de.org repo and re-labeled to include needs-triage for the docs sig. We will occasionally review O3DE repo items which have not had a SIG assigned or been triaged.
• Feature requests which are QoL improvements or would be primarily documentation-oriented, such as requests for full game templates and samples (i.e. a request for a 3rd person shooter sample to be bundled with O3DE.)
• Features which are reaching a stage of maturity where the Docs-Community SIG needs to be aware of the current feature state and progress, in order to assist with documentation or help the SIG plan for anything else required.
• Features where a quick grep of the website source reveals a large number of impacted files; i.e. renaming a core component, modifying a core feature behavior, or some other work that has an outsized impact. Often this would be considered an "Impactful Change" but for large enough impactful changes, you should err on the side of engaging with SIG Docs-Community. It's easier for us to say "no" than for us to play catch-up later when we should have said "yes".

The SIG does not need to be informed of new feature work when it comes in as an issue - the SIG should be engaged at the RFC stage. For new features SIG Docs-Community should be involved early, to help establish what is needed to meet the minimum viable content guidelines for docs (TBD) and if there is any specialized content that the SIG can help produce or would request as part of the submission (such as sample code or projects.)

When should SIG Docs-Community review a PR?

On most code reviews, you will not need a dedicated reviewer from SIG Docs-Community. The only time you should request a reviewer from our pool is:

• You have a question about how the PR impacts documentation which was not considered when triaging the issue
• A large amount of user-facing text is impacted in the PR (i.e. you have rewritten a significant number of tooltips for an Editor-facing Component). The exact amount that makes a "large amount" is intentionally nebulous; a good metric is that if "most" or "all" of a file's text has changed, or you anticipate that it will change over a series of pull requests to address a single core issue, make sure that SIG Docs-Community is involved.
• Somebody from our SIG has explicitly requested addition as a reviewer

Mitigation of critical misses

A "critical miss" would be considered any issue which:

• Does not have sig/docs-community as a label on the issue or pull request
• Would be ranked as priority/critical or higher by SIG Docs-Community

While we're unlikely to have a critical miss under the suggested guidelines, we require a mitigation plan in the event that there is one. The proposed plan is to:

• Engage with the SIG which did not correctly identify the issue, and ensure that they had access to the guidelines.
• Cover the guidelines with the offending SIG to determine if there was a gap in the description of when sig/docs-community should be labeled as a stakeholder of the issue or PR, and make any appropriate amendments to the triage guidelines.
• Schedule the identified work under the appropriate priority/X label (priority/critical or priority/blocker, by definition). Docs contributor bandwidth is extremely low, and so even high priority items are likely to languish.

What are the advantages of the suggestion?

sig/docs-community is identified as a stakeholder by other SIGs, preventing us from having to attend and participate in every other individual SIG triage.

What are the disadvantages of the suggestion?

Relies on the best judgement of other SIGs to correctly identify stakeholders. This has two major consequences:

• SIGs must be aware of our guidelines for involvement, and follow them.
• The Docs and Community SIG will inevitably be left off of a critical item that we should be stakeholders for, and we must have a mitigation plan.

How will this be work within the O3DE project?

During individual SIG triage sessions, the group will be required to evaluate the incoming issues affecting them on documentation, following these guidelines. This will be an additional process overhead to SIG triage but is preferable to every other alternative.

Scope of work

The definition of the process to be followed during triage is in this document. The remainder of work will be:

• Formalize this document into something inside of the SIG repo itself
• Communicate information to stakeholder SIGs that they are now required to follow this process if they would like the involvement of sig-docs-community

Are there any alternatives to this suggestion?

• A member (or members, or rotating group, or however it is "assigned") of sig-docs-community is responsible for attending every other SIG triage.
• Do nothing; sig-docs-community is no longer a "stakeholder group" on any O3DE work and focused solely on issues reported to o3de.org.

What is the strategy for adoption?

• Produce a formal document for the SIG describing when we should be tagged on issues reported to the o3de repo.
• Communicate to SIGs through Discord and the mailing lists that they are now responsible for following this guidance.
• Provide availability of Docs-Community members to voluntarily attend triage sessions during an early period of implementing this process (the first 30-45 days) and assist SIG members with understanding the new guidelines.

[lmbr-pip]

Firstly:

Features which are reaching a stage of maturity where the Docs-Community SIG needs to be aware of the current feature state and progress, in order to assist with documentation or help the SIG plan for anything else required.

This is not a triage related issue, and while does cover advice of when you should engage Docs-community, it does not really fit in the proposed purpose of this RFC. Expectation is that SIGs will pay more attention to features in flight once the per SIG roadmaps are available.

Secondly, its worth noting C that SIG-Chair(s) are voluntary positions. The more cognitive load we are adding here the more time we are demanding of SIG-Chair(s) so guidance should be short, concise and easy to follow so SIGs can absorb it asap.

IMHO deliverables of this should be:

• Very clear, brief guidance as when docs should be engaged.
• Advice is added to the standard triage guide in the community repro (if its ever published - see Provide common issue triage guide for O3DE community#130)
• Engagement with the SIG-Chair(s) via the mailing list, SIG of SIGS meeting (last TSC meeting of each month) and in sig-all once once advice is published. Worth noting that many SIGs have their own triage guides, because the community central one is still missing, so it will take time for changes to be be absorbed.

[chanmosq]

We should bring this up again, possibly the o3de/community repo is a good place to have this conversation. I think some parts of this guidance can be revived - specifically about providing guidance on when and how to involve sig-docs-community during triage.

Note, this code review guidance references this issue for guidance: https://github.com/o3de/community/blob/main/guides/o3de-code-review-guidelines.md

Closing, @sptramer can you revisit this issue and restart the conversation in o3de/community repo?

[chanmosq]

We should also require adding sig-docs-community for any code PRs about deprecation