SIG-Docs-Community Election | Nominations 18 Aug - 29 Aug | Elections 31 Aug - 14 Sep

Hello all sig-docs-community:

For the first year of O3DE, @sptramer and @FiniteStateGit have served as the chairpersons of the Documentation & Community Special Interest Group. Now it's time for our second election season, leading into a 6-month term, which is shorter than the original sig-docs-community term length. We think that electing new representatives at this time in the leadup to the 22.10 release and closing of the year of 2022 will help us grow the SIG and better understand our users and community. Due to the expertise of the chairs and SIG members during the first year of O3DE, we have focused very heavily on documentation, and encourage the nomination of persons who are more focused on building our community.

The following things have changed since our last election:

Terms are now officially 6 months, meaning our next election will be held in mid-March of 2023. Chairpersons may relinquish their chairship at any point and for any reason, but nominees should try and commit to their full term.
Nominees are no longer required to be reviewers or maintainers, but reviewer/maintainer status is something nominees should highlight.
Nominees should have at least some familiarity with open source, and one of either technical writing or community management/building.
Nominees should provide a statement regarding their candidacy and what they see as important for the SIG to handle over the next 6-12 months. It's OK for a chair to set direction to continue after their term!
Chairs are not required to provide on-call coverage of any sort.

The chair / co-chair roles

The chair and co-chair serve equivalent roles in the governance of the SIG and are only differentiated by title in that the highest vote-getter is the chair and the second-highest is the co-chair. The chair and co-chair are expected to govern together in an effective way and split their responsibilities to make sure that the SIG operates smoothly and has the availability of a chairperson at any time.

Unless distinctly required, the term "chairperson" refers to either/both of the chair and co-chair. If a chair or co-chair is required to perform a specific responsibility for the SIG they will always be addressed by their official role title.

Chairs are not required to provide "on-call" support of any kind as part of their chairship. The O3D Foundation is responsible for addressing any high-severity issues related to documentation or community which would impact the immediate operation of the O3DE project or may result in legal liability of the O3D Foundation.

Responsibilities

Schedule and proctor regular SIG meetings on a cadence to be determined by the SIG.
Planning and strategy for documentation and community building for O3DE.
Serve as a source of authority (and ideally wisdom) with regards to O3DE documentation. Chairpersons are the ultimate arbiters of many documentation standards, processes, and practices.
Act as representatives of the community, and provide advice to other SIGs, the Technical Steering Committee (TSC), and the Foundation on community building and management.
Coordinate with partners and the Linux Foundation and Marketing Committee regarding official community events.
Regularly participate in O3DE discussion channels such as our mailing lists, GitHub discussions, and Discord.

Nominations and election

Nomination requirements

Nominees must be an active contributor to Open 3D Engine in some fashion. Nominees should include any information on their work in O3DE (whether that is actively participating in Discord/forums/email, producing code submissions, producing docs submissions, or providing external tutorials or resources).

If you are nominated by somebody other than yourself, you're encouraged to provide your own statement (however brief). If you would like to decline a nomination, please do so on this issue before the nomination deadline.

How to nominate

Nominations will be accepted beginning with the date of posting of this issue, until 2022-08-29 12:00PM PT.
Nominate somebody (including yourself) by responding to this issue with:

A statement that the nominee should be nominated for a chair position in the Documentation & Community SIG.
If you are nominating somebody else: Explain why you're doing so, provide some examples of their relevant contributions, and make sure that they are @-ed by their GitHub alias so they receive a notification and can respond.
If you are nominating yourself: Provide a brief statement on your reasons for running for chairperson, and any information you think is useful about what you see as an ideal direction for O3DE with regards to documentation or community.
The name under which the nominee should be addressed. Nominees are allowed to contact the election proctor to have this name changed.
The GitHub username of the nominee. (Self-nominations need not include this; it's on your post.)
Nominee's Discord username. Chairpersons must be active in the O3DE Discord if elected.

By accepting a nomination you acknowledge that you believe you can faithfully execute the role required of a chairperson for sig-docs-community for the next 6 months. Chairpersons may relinquish their chairship at any time and for any reason.

If only one nomination is received, nominations will remain open for an additional 2 weeks.

Election process

In the case where there are 2 candidates at the end of the nomination period, if they agree on chair and co-chair, no vote will be needed.

Otherwise, the election for chairpersons of sig-docs-community will occur one week after the nominations period closes.

Voting will be performed through an online mechanism TBD, starting 2 days after nominations are closed. The election voting will last for 2 weeks, tentatively scheduled for 2022-08-31 12:00PM PT until 2022-09-14 12:00PM PT.

Election results will be announced on or before 2022-09-15.

The elected chairpersons will begin serving their term at the start of the first sig-docs-community meeting following the end of the election, during which the handoff will occur.

Proposed SIG-Docs meeting agenda for 2021-07-01

Meeting Details

Date/Time: July 1, 2021 @ 3PM GMT / 8:00 AM PTDate, Year @ XX:XXpm UTC / XX:XXpm ET
Location: Discord SIG-Docs Voice Room
Moderator: Stephen Tramer
Note Taker TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

The SIG will provide some updates on our final preparation for launch and settle any remaining urgent business affecting the community.

Open action items

@sptramer - Complete o3de/o3de.org#562
Denis D. - Contact Alex D. and Melissa A. at Amazon about putting together materials for a launch-proximate video on OSS for game devs
SIG - Resolve writing style PR checklist o3de/o3de.org#563

Newly resolved items

✅ Guidelines on writing style in style guide o3de/o3de.org#561

Initial Agenda

This meeting has no initial agenda. Items will be taken up as proposed and as time allows based on the business the SIG brings.

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed SIG-Docs meeting agenda for 2022-08-09

Meeting Details

Date/Time: Aug 09, 2022 @ 11:00AM PT
Location: Discord SIG-Docs Voice Room
Moderator: @sptramer
Note Taker: @FiniteStateGit

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

What happened since the last meeting? - The creator of this issue is responsible for providing a brief summary here to be used as an update to start any important discussions.

Open action items

Newly resolved items

✅ Unordered list of action items resolved since the last meeting.
✅ ...

Initial Agenda

The pre-approved agenda for this meeting is as follows:

SIG Updates! - Stephen Tramer - 10m
- AWS Content evaluation
- Official triage process!
- SIG election season begins 8/10! Submit your name for candidacy and follow the forthcoming instructions. Nominations will run until at least 8/31 and voting will be held 9/2 - 9/11.
Active discussions - Stephen Tramer / Various - 15m
- https://github.com/o3de/sig-docs-community/discussions
Active issues / RFCs - Stephen Tramer / Various - 15m
- https://github.com/o3de/sig-docs-community/issues

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed SIG-Docs meeting agenda for 2022-03-15

Meeting Details

Date/Time: March 15, 2022 @ 11:00 am PT
Location: Discord SIG-Docs Voice Room
Moderator: Name
Note Taker: Name

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

Upcoming release (tentatively 05/2022)
- TSC not proposing an LTS in 2022
Logo change
Audit activity
Project: Lua API reference
Project: Programmer Guide reorg

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Finalize RFC #32 - Stephen Tramer - 10m
- Accept/reject the current proposal for the main/dev split. Things to consider during this discussion:
  - We can publish the development branch to a non-friendly URL, development--staging.o3deorg.netlify.app.
  - The TSC is reporting that people are abandoning box releases if they need to use O3DE for serious development, due to the pace of dev regarding new features and the lack of backporting bug fixes (due to the lack of a dedicated stabilization team.)

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed SIG-Docs meeting agenda for 2022-12-13

Meeting Details

Date/Time: December 13, 2022 @ 10:30 10:30am PT
Location: Discord SIG-Docs Voice Room
Moderator: @chanmosq
Note Taker: Name

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

What happened since the last meeting? - The creator of this issue is responsible for providing a brief summary here to be used as an update to start any important discussions.

docs.o3de.org domain has been removed (#83)
Initial PR for the Engine Developer Guide (o3de/o3de.org#2162)
New codeowners file in o3de.org
Revised Documentation and Community Roles and created new nomination forms.
- Website Reviewers: A new reviewers team specifically for website.
- Community Specialist: A team specifically for community-related content.
- Technical Reviewers: Technical docs reviewers are SIG-specific, and each SIG may decide how to manage this group.

Open action items

#88
See https://github.com/orgs/o3de/projects/15/views/1.

Newly resolved items

✅ #73

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Agenda item name - Presenter - Length of time
- Description of the item
...

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed SIG-Docs-Community Feature Grid

Features(modules) are organized by workflow (in H3); they include the concepts, tools, and components associated with the workflow. Features are scored on four metrics: the completeness of conceptual material, tutorial content, sample content, and the API documentation for reflected features. Metrics that are not scored for a feature are labeled 'N/A'. A documentation link to conceptual material is listed in the last column. In some cases, I could not identify a primary location to link to a feature with partial coverage.

Sig-Docs-Community

Onboarding

Module	Conceptual Material	Tutorial Content	Sample Content	API Documentation	Documentation Link
Onboarding	🟢 Complete	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/welcome-guide/
Engine Config and Build	🟢 Complete	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/build/
Build Platform - Windows	🟢 Complete	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/welcome-guide/setup/installing-windows/
Build Platform - Linux	🟢 Complete	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/welcome-guide/setup/installing-linux/
Build Platform - Android	🟢 Complete	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/platforms/android/generating_android_project_windows/
Build Platform - MacOS	🔴 None	🔴 None	⭕ N/A	⭕ N/A
Project Config and Build	🟢 Complete	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/project-config/
Gem System	🟡 Partial	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/programming/gems/
Gem Catalog	🟢 Complete	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/project-config/add-remove-gems/
Editor	🟢 Complete	🟡 Partial	⭕ N/A	🔴 None	https://www.o3de.org/docs/user-guide/editor/
System Components	🔴 None	🟡 Partial	⭕ N/A	🔴 None
Viewport	🟢 Complete	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/editor/viewport/
Entity Outliner	🟡 Partial	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/editor/entity-outliner/
Entity Inspector	🟡 Partial	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/editor/entity-inspector/
Console	🟢 Complete	🟡 Partial	⭕ N/A	🟡 Partial	https://www.o3de.org/docs/user-guide/editor/console/
Asset Browser	🔴 None	🟡 Partial	⭕ N/A	⭕ N/A
Asset Editor	🔴 None	🟡 Partial	⭕ N/A	⭕ N/A
Project Manager	🟢 Complete	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/project-config/project-manager/
CLI	🟢 Complete	🟡 Partial	⭕ N/A	🟢 Complete	https://www.o3de.org/docs/user-guide/project-config/cli-reference/

Experience design

Module	Conceptual Material	Tutorial Content	Sample Content	API Documentation	Documentation Link
Entities	🟡 Partial	🟡 Partial	🔴 None	🔴 None
Levels	🔴 None	🟡 Partial	🔴 None	🔴 None
Prefabs	🔴 None	🟡 Partial	🔴 None	🔴 None
Physics	🟡 Partial	🟡 Partial	🔴 None	🔴 None	https://www.o3de.org/docs/user-guide/interactivity/physics/
Event Buses	🟡 Partial	🔴 None	🔴 None	🟡 Partial	https://www.o3de.org/docs/user-guide/programming/ebus/
AZ Events	🔴 None	🔴 None	🔴 None	🔴 None
Scripting	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/scripting/
Audio	🟢 Complete	🔴 None	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/interactivity/audio/
AI	🔴 None	🔴 None	🔴 None	⭕ N/A
Input	🟡 Partial	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/interactivity/input/
Cameras	🔴 None	🔴 None	🔴 None	⭕ N/A
UI	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/interactivity/user-interface/
Audio Components	🟢 Complete	🔴 None	🔴 None	🟡 Partial	-
Camera Components	🟢 Complete	🔴 None	🔴 None	🟢 Complete	-
Gameplay Components	🟢 Complete	🟡 Partial	🔴 None	🟢 Complete	-
PhysX Components	🟢 Complete	🟡 Partial	🔴 None	🔴 None	-
Scripting Components	🟡 Partial	🟡 Partial	🔴 None	🟡 Partial	-
Shape Components	🟢 Complete	🔴 None	🔴 None	🟢 Complete	https://www.o3de.org/docs/user-guide/components/reference/shape/
Transform Component	🟢 Complete	🟡 Partial	🔴 None	🟡 Partial	-
Non-uniform Scale Component	🟢 Complete	🔴 None	🔴 None	🟡 Partial	-
Input Components	🟡 Partial	🟡 Partial	🔴 None	🟡 Partial	-
UI Components	🟡 Partial	🟡 Partial	🔴 None	🔴 None	-
UI Canvas Components	🟢 Complete	🟡 Partial	🔴 None	🔴 None	https://www.o3de.org/docs/user-guide/interactivity/user-interface/components/
UI Editor	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/interactivity/user-interface/editor/
Script Canvas	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/scripting/script-canvas/
Lua Editor	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/scripting/lua/lua-editor/
PhysX Configuration	🟢 Complete	🟡 Partial	🔴 None	🔴 None	https://www.o3de.org/docs/user-guide/interactivity/physics/nvidia-physx/configuring/

Actor development

Module	Conceptual Material	Tutorial Content	Sample Content	API Documentation	Documentation Link
Actors	🟡 Partial	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/components/reference/animation/actor-component-entity-setup/
Animation	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/visualization/animation/char-intro/
Animation Components	🟢 Complete	🟡 Partial	🔴 None	🟡 Partial	-
PhysX Components	🟡 Partial	🟡 Partial	🔴 None	🔴 None	-
Animation Editor	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/visualization/animation/

World building

Module	Conceptual Material	Tutorial Content	Sample Content	API Documentation	Documentation Link
Terrain	🔴 None	🟡 Partial	🔴 None	⭕ N/A
Vegetation	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/gems/reference/environment/vegetation/
Gradient Components	🟡 Partial	🟡 Partial	🔴 None	🟢 Complete
Surface Data Components	🟡 Partial	🔴 None	🔴 None	⭕ N/A
Terrain Components	🟡 Partial	🟡 Partial	🔴 None	🟢 Complete
Vegetation Components	🟢 Complete	🟡 Partial	🔴 None	🟢 Complete	https://www.o3de.org/docs/user-guide/gems/reference/environment/vegetation/
Landscape Canvas	🔴 None	🔴 None	🔴 None	⭕ N/A

Look development

Module	Conceptual Material	Tutorial Content	Sample Content	API Documentation	Documentation Link
Assets	🟡 Partial	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/assets/
Materials	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/atom-guide/look-dev/materials/
Shaders	🟡 Partial	🔴 None	🔴 None	⭕ N/A	https://www.o3de.org/docs/atom-guide/look-dev/shaders/
Atom Renderer	🟢 Complete	🟡 Partial	🟢 Complete	⭕ N/A	https://www.o3de.org/docs/atom-guide/
Cinematics	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/visualization/cinematics/
Asset Processor	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/assets/asset-processor/
Asset Pipeline	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/assets/pipeline/
Python Asset Builder	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/assets/builder/
Atom Components	🟡 Partial	🟡 Partial	🔴 None	🟡 Partial
Material Editor	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/atom-guide/look-dev/materials/material-editor/
Track View Editor	🟢 Complete	🟡 Partial	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/visualization/cinematics/track-view/

Multiplayer

Module	Conceptual Material	Tutorial Content	Sample Content	API Documentation	Documentation Link
Multiplayer	🟢 Complete	🟡 Partial	🟡 Partial	🔴 None	https://www.o3de.org/docs/user-guide/gems/reference/multiplayer/
Networking Components	🟢 Complete	🟡 Partial	🟡 Partial	🔴 None	https://www.o3de.org/docs/user-guide/networking/
Cloud Components	🟢 Complete	🔴 None	🔴 None	🔴 None	https://www.o3de.org/docs/user-guide/gems/reference/aws/

Project development and team collaboration

Module	Conceptual Material	Tutorial Content	Sample Content	API Documentation	Documentation Link
Source Control	🔴 None	🔴 None	🔴 None	⭕ N/A
Platform Development	🟡 Partial	🔴 None	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/platforms/
Platform Development - Windows	🟡 Partial	🔴 None	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/platforms/windows/
Platform Development - Linux	🟡 Partial	🔴 None	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/platforms/linux/
Platform Development - Android	🟡 Partial	🔴 None	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/platforms/android/
Platform Development - MacOS	🔴 None	🔴 None	🔴 None	⭕ N/A
Programming	🟢 Complete	🟢 Complete	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/programming/
Testing	🟢 Complete	🟢 Complete	🔴 None	⭕ N/A	https://www.o3de.org/docs/user-guide/testing/
Graph Canvas	🔴 None	🔴 None	🔴 None	⭕ N/A

Editor extension

Module	Conceptual Material	Tutorial Content	Sample Content	API Documentation	Documentation Link
Component Development	🟢 Complete	🟡 Partial	🟡 Partial	⭕ N/A	https://www.o3de.org/docs/user-guide/programming/components/
Tools UI	🟢 Complete	🟡 Partial	🟡 Partial	⭕ N/A	https://www.o3de.org/docs/tools-ui/

Packaging and deployment

Module	Conceptual Material	Tutorial Content	Sample Content	API Documentation	Documentation Link
Asset Bundling	🟢 Complete	🟢 Complete	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/packaging/asset-bundler/
Release Build	🟡 Partial	🟡 Partial	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/packaging/overview/
Release Platform - Windows	🟢 Complete	🟢 Complete	⭕ N/A	⭕ N/A	https://www.o3de.org/docs/user-guide/packaging/windows-release-builds/
Release Platform - Linux	🔴 None	🔴 None	⭕ N/A	⭕ N/A
Release Platform - Android	🔴 None	🔴 None	⭕ N/A	⭕ N/A
Release Platform - MacOS	🔴 None	🔴 None	⭕ N/A	⭕ N/A

SIG Reviewer/Maintainer Nomination: @paucom

Nomination Guidelines

Documentation reviewer

6+ documentation contributions merged to o3de.org or O3DE
2+ Reviewer or Maintainers of the Documentation and Community SIG.

Maintaining status: 4+ Pull Requests reviewed per month.

I would like to nominate: @paucom, to become a Docs Reviewer on behalf of sig-docs-community. I verify that they have fulfilled the prerequisites for this role.

NOTE: Paul's contributions are not directly to the repository - he serves a unique role as the funded copyeditor for O3DE documentation at AWS. His contributions - as most copyeditor contributions are - come in the form of large reviews on content to make sure it conforms to style.

Nominee's GitHub Profile: @paucom

Reviewers & Maintainers that support this nomination should comment in this issue.

Develop Feature Grid for sig-docs-community

Per RFC #64, this task is to integrate the feature grid for docs into the existing feature grid.
#68

Proposed SIG-Docs meeting agenda for 2021-11-18

Meeting Details

Date/Time: November 18, 2021 @ 1700 UTC / 9:00AM PT
Location: Discord SIG-Docs Voice Room
Moderator: Stephen Tramer
Note Taker: TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

No official updates from the SIG at this time.

Open action items

@spotz - Onboarding for contributors to o3de.org - how to make your first contributions, etc. (meta info on contributing)
@sptramer - Official taxonomy and structure information
@sptramer - Complete "Next Release" roadmap for docs

Initial Agenda

The pre-approved agenda for this meeting is as follows:

SIG updates - Stephen Tramer - 20m
- All the SIG news that's fit to print:
  - Exporting items for the roadmap, "enhancing" the content backlog, and other progress in bringing forth known issues to the community.
  - Ongoing reviewer rotation and capacity issues.
  - "What's in the release" (docs-wise)
  - Scheduling regular sig-docs-community meetings starting January 2022 - let's set a cadence
  - Adjusting schedule of sig-docs-community triage?
  - Chair (and other) elections process - we have elections guidance! o3de/community#105
Versioning documentation
- With LTS versions coming, we need to provide guidance on how documentation should be updated and propagated through versions to match the state of O3DE's repo
- Would documentation ever be versioned? How does a user using a "version 1" get the right state of documentation? (vs a user using development)

The remaining hour of this meeting is intentionally held open for community-proposed agenda items. Please read the following section(s) on how to propose and vote.

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

RFC NEEDED: C++ API reference generation and coverage chart

For a while now, we've known that we need an RFC (or two) which will cover the following topics:

Being able to automatically create API reference generation from O3DE source - this is currently a manual process using external files from the o3de repo, and @sptramer has some notes and ideas on how it could work best with O3DE, but not enough time for a full RFC.
Publishing API reference updates to development on a regular cadence. RFC to provide details. Publishing for releases can still be a manual process (but should be as automated as possible, as described).
Generating lcov (or similar) API coverage information for the feature grid, as well as suggested metrics for hitting YELLOW and GREEN. These suggestions will need to be approved by the TSC. @lmbr-pip has some background and details on this, as he's generated some internal lcov information for sig-networking engineers.

Undoubtedly there is more to consider! Please leave a comment or begin a pre-RFC discussion on the forums if you're interested in helping with this process.

SIG Reviewer/Maintainer Nomination: @chanmosq

Documentation maintainer

Has been a Reviewer for 2+ months
8+ reviewed Pull Requests in the previous 2 months
2+ D&C SIG Maintainers who support promotion.

Maintaining status: 8+ Pull Requests reviewed per month.

Reviewer/Maintainer Nomination

Fill out the template below including nominee GitHub user name, desired role and personal GitHub profile

I would like to nominate @chanmosq to become a Maintainer on behalf of sig-docs-community. I verify that they have fulfilled the prerequisites for this role.

NOTE: @chanmosq has been unofficially performing the role of Reviewer for 6+ months, since O3DE launch.

Nominee's GitHub Profile: @chanmosq

Reviewers & Maintainers that support this nomination should comment in this issue.

Proposed SIG-Docs meeting agenda for February-08-2022

Meeting Details

Date/Time: February 8, 2022 @ 11:00am PST / 7:00pm UTC
Location: Discord SIG-Docs Voice Room
Moderator: SIG-Docs chair
Note Taker: TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

Regular SIG-Docs meeting scheduled for the second Tuesday of every month at 11am PST / 7pm UTC.

Open action items

Newly resolved items

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Sig Updates - Stephen Tramer - 10m
- Two releases! (2111.1 and 2111.2)
- Chair elections! @sptramer and @FiniteStateGit are the chairs of sig-docs-community.
- Staffed community manager for our "and community": Amy Finch (Finchy, @aFinchy)
- 2022 planning season: Propose projects, write RFCs, and help build our roadmap for the first part of 2022.
Reviewer/Maintainer promotions - Stephen Tramer - 5m
- #28
- #27
- #26
- #30
Project proposals and updates - Stephen Tramer - 10m:
- Active projects
- #31

The remaining time of this meeting is for community agenda items. Please remember to propose and vote!

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

RFC NEEDED: Documentation deprecation path

There is an accepted RFC (o3de/sig-release#50) for a deprecation path for code in O3DE. As raised on the RFC, docs is downstream of the deprecation process and needs to have our own policies and practices put in place to handle deprecation.

This RFC should address:

How documentation fits into the deprecation process, including when engineers tell us deprecation is starting
What documentation should exist around deprecation
Unified messaging strategy for deprecated content items

Undoubtedly there is more to consider! Please leave a comment or begin a pre-RFC discussion on the forums if you're interested in helping with this process.

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

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.

Proposed SIG-Docs meeting agenda for 2022-07-12

Meeting Details

Date/Time: Month Date, Year @ 1800 UTC / 11:00AM PT
Location: Discord SIG-Docs Voice Room
Moderator: Finite_State
Note Taker: TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

Joint SIG/TSC Meeting held 6/28:
- All SIGs are requested to revise their repo Readmes with the information found here:
  o3de/tsc#37
- There is a new Notable tag to use for PRs or Issues that O3DE marketing should broadcast.
- SIG-graphics-audio settled on Mitsuba as a ground truth reference for all things graphics.
- RoddieKieley is a new chair for the TSC.
- O3DCon Call for Proposals is available and submissions would be appreciated.

Open action items

Newly resolved items

✅ Website refresh proposal & review (comments due by 07/01): https://docs.google.com/presentation/d/1kccEEmn6fdOgsarql0BB9Y7KxNdXTdp6/edit#slide=id.g13563bc39b3_0_262
✅ ...

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Agenda item name - Presenter - Length of time
- Description of the item
...

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed SIG-Docs meeting agenda for 2022-11-22

Meeting Details

Date/Time: November 22, 2022 @ 10:30 am PT
Location: Discord SIG-Docs Voice Room
Moderator: Chanelle Mosquera
Note Taker: Name

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

What happened since the last meeting? - The creator of this issue is responsible for providing a brief summary here to be used as an update to start any important discussions.

o3de-extras repo is now a canonical external repo for O3DE. See o3de/o3de#11862. Open question: What will this mean for docs?
Upcoming o3de/tsc#59, where we'll raise awareness for a codeowners file for o3de.org.

Open action items

#70 - Voting time.
#73 - now ready for review! Expedited review is requested. Planned merge date: (?)

See https://github.com/orgs/o3de/projects/15/views/1.

Newly resolved items

✅ Unordered list of action items resolved since the last meeting.
✅ ...

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

SIG Elections 12/3 - 12/17 Nominations

SIG Docs-Community chair / co-chair elections for 2022

For the first year of O3DE, the D&C chair has been staffed as an interim position. It's time to hold some official elections, following some of the proposed guidance but with our own process due to the holiday season and in order to expedite the elections into next year.

The chair / co-chair roles

The chair and co-chair serve equivalent roles in the governance of the SIG and are only differentiated by title in that the highest vote-getter is the chair and the second-highest is the co-chair. The chair and co-chair are expected to govern together in an effective way and split their responsibilities to make sure that the SIG operates smoothly and has the availability of a chairperson at any time.

Unless distinctly required, the term "chairperson" refers to either/both of the chair and co-chair. If a chair or co-chair is required to perform a specific responsibility for the SIG they will always be addressed by their official role title.

In particular, if both chairpersons would be unavailable during a period of time, the chair is considered to be an on-call position during this period. As the higher vote-getter they theoretically represent more of the community and should perform in that capacity under extenuating circumstances. This means that if there is an emergency requiring immediate action from the Documentation & Community SIG, the chair will be called to perform a responsibility.

Responsibilities

Schedule and proctor regular SIG meetings on a cadence to be determined by the SIG.
Serve as a source of authority (and ideally wisdom) with regards to O3DE documentation. Chairpersons are the ultimate arbiters of many documentation standards, processes, and practices.
Participate in the SIG Docs-Community Discord channel and on the GitHub Discussion forums.
Serve as a representative of the broader O3DE community to all other SIGs, partners, the governing board, and the Linux Foundation.
Represent the SIG to O3DE partners, the governing board, and the Linux Foundation.
Coordinate with partners and the Linux Foundation regarding official community events.
Represent (or select/elect representatives) to maintain relationships with all other SIGs as well as the marketing committee.
Serve as an arbiter in SIG-related disputes.
Coordinate releases with SIG Release.
Assist contributors in finding resources and setting up official project or task infrastructure monitored/conducted by the SIG.
Long-term planning and strategy for the course of documentation for O3DE.
Maintain a release roadmap for the O3DE documentation.

Additionally, at this stage of the project, the SIG chairpersons are expected to act in the Maintainer role for review and merge purposes only, due to the lack of infrastructure and available reviewer/maintainer pool.

... And potentially more. Again, this is an early stage of the project and chair responsibilities have been determined more or less ad-hoc as new requirements and situations arise. In particular the community half of this SIG has been very lacking due to no infrastructural support, and a chairperson will ideally bring some of these skills.

Nomination

Nomination may either be by a community member or self-nomination. A nominee may withdraw from the election at any time for any reason until the election starts on 12/3.

Nomination requirements

For this election, nominees are required to have at minimum two merged submissions to o3de.org (must be accepted by 2022-01-31). This is to justify any temporary promotion to Maintainer as required by this term as chairperson. Submissions may be in-flight as of the nomination deadline (2021-12-03 12PM PT), but the nominee must meet the 2-merge requirement by the end of the election or they will be removed from the results.

Any elected chairperson who does not currently meet the Maintainer status will be required to work with contributors from the SIG to produce an appropriate number of accepted submissions by January 31, 2022 or they will be removed and another election will be held.

The only other nomination requirement is that the nominee agrees to be able to perform their required duties and has the availability to do so, taking into account the fact that another chairperson will always be available as a point of contact.

How to nominate

Nominate somebody (including yourself) by responding to this issue with:

A statement that the nominee should be nominated for a chair position in the Documentation & Community SIG. Nominees are required to provide a statement that they understand the responsibilities and requirements of the role, and promise to faithfully fulfill them and follow all contributor requirements for O3DE.
The name under which the nominee should be addressed. Nominees are allowed to contact the election proctor to have this name changed.
The GitHub username of the nominee (self-nominations need not include this; it's on your post.)
Nominee's Discord username (sorry, but you must be an active Discord user if you are a chairperson.)

Election process

The election will be conducted between 2021-12-03 12:00PM PT and 2021-12-17 12:00PM PT and held through an online poll. Votes will be anonymous and anyone invested in the direction of O3DE and its documentation may vote. If you choose to vote, we ask that you be familiar with the nominees.

The current interim chair (@sptramer) will announce the results in the sig-docs-community Discord and on the sig-docs-community O3DE mailing list no later than 2021-12-17 1:00PM PT. At that time if there is a dispute over the result or concern over vote tampering, voting information will be made public to the extent that it can be exported from the polling system and the SIG will conduct an independent audit under the guidance of a higher governing body in the foundation.

The elected chairpersons will begin serving their term on 2022-01-01 at 12AM PT. Tentatively SIG D&C chairs will be elected on a yearly basis. If you have concerns about wanting to replace chairs earlier, please discuss in the request for feedback on Governance.

Proposed SIG-Docs meeting agenda for 2022-08-23

Meeting Details

Date/Time: August 23, 2022 @ 1730 UTC / 10:30 AM PT
Location: Discord SIG-Docs Voice Room
Moderator: FiniteStateGit
Note Taker: TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

SIG triage guide has been added to the repo: https://github.com/o3de/sig-docs-community/blob/main/governance/sig-triage.md
#57
#54

Open action items

Newly resolved items

✅ Monthly SIG meetings moved to 10:30AM PST on the 2nd and 4th Tuesday of the month.
✅ #46
✅ #47

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Determine open action items to carry forward into next SIG term. #45

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed RFC: Merge access control and designated ownership of o3de/o3de.org

When presented in italics, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF RFC 2119.

Clarification of website section ownership

This RFC is to establish a system where we can separate out different maintainers and owners of the o3de.org website. Currently, sig-docs-community ("the SIG") is managing all sections of the website under the policy of requiring two reviewers, which impacts things like our ability to publish content that documentation reviewers shouldn't need to be involved in.

This RFC is a proposal to create the following:

A set of representative groups which maintain either GitHub organizations or groups within the O3DE project that can be assigned to approve issues, directly submit repo changes without approval (in high-severity events), or participate in review processes outside of sig-docs-community norms or without the participation of the SIG. The following groups are suggested to start:
- sig-dc-documentation reviewer and maintainer groups, who have permissions to review and change content/docs, content/community, and content/contribute as well as the associated media and layouts.
- sig-dc-community reviewer and maintainer groups, who have permissions to review and change content/blog, content/community/, content/contribute, and the associated media and layouts. Community changes should have at least one approver from sig-docs-community outside this group, which would be a process change.
- o3df-representatives, a group of representatives from the Open 3D Foundation. At minimum, this group should have permission to static/img and layouts/partials for the management of logos, partners, and events. The Foundation may also be required to review certain content before going live.
- o3de-website, a group dedicated to the maintenance and development of the o3de.org website. This group should have access to all HTML, JS, CSS/SASS, and other webdev-related file types. The website group must not have permission to merge docs.
An enforcement mechanism for these restrictions. GitHub CODEOWNERS support is recommended.

Note that the representative groups are not mutually exclusive. We expect that there will be crossover between documentation and blog reviewers, for example; Documentation will likely want to provide (or require) copyedit support for blogs.

NOTE: This RFC does not affect technical review processes. Technical reviewers must not have merge permissions on o3de.org and should participate in review on a case-by-case basis.

What is the relevance of this feature?

Currently, there are a number of situations in which sig-docs-community reviewers and maintainers are blockers on critical items, such as o3de/o3de.org#1799 (Press releases and announcements) or o3de/o3de.org#1836 (materials owned and managed by the Open 3D Foundation / Linux Foundation). In addition, there have been a number of kind/website or kind/foundation issues coming up during sig-docs-community triage.

We need to effectively delegate responsibilities to other organizations and projects where documentation approval should not or must not be a blocker. In addition, as the website becomes more complicated and undergoes active development, it's important to remember that sig-docs-community should not be the current owner of website development as covered in sig-docs-community charter due to the SIG's lack of ownership of "website UX", which is also not part of the scope of the sig-ui-ux charter.

In addition to establishing these groups, their permissions and access control for the GitHub repository settings need to be enforced. Further details on enforcement are located in the "Feature Design Description - Enforcement mechanism" section.

What are the advantages of the feature?

Clearly delegate roles and responsibilities for ownership of website areas.
Prevents non-representative groups from committing to (or reviewing) areas of non-ownership.
Removes sig-docs-community/reviewers and maintainers group from involvement in changes unrelated to documentation.
Provides an official channel for the Open 3D Foundation to manage their access control to the o3de.org repo.
Provides a delegated group which can review website code changes.
Provides a delegated group which can submit and publish blogs under their own system.
Sets up a system of infrastructure for additional groups, projects, or stakeholder teams for the website as needed.
Uses a standard enforcement mechanism for review and write access requirements on GitHub.

What are the disadvantages of the feature?

Creates the additional bureaucracy of multiple stakeholder groups in some approval processes, which may actually slow them down.
"Community" and "Website" reviewer groups will need to amend the reviewers-maintainers governance.
Further muddies some of the confusion around ownership of the website experience in the sig-docs-community charter. The SIG proposed website-dev as a maintainer group and will need to collaborate with it.
Proposed code ownership mechanisms may prove to be too restrictive for certain groups to operate effectively.

Feature design description

This section outlines four areas of feature design: Group responsibilities, enforcement mechanisms, ownership mapping, and SIG changes.

Distinct groups and responsibilities

The major areas we've identified where there should be specialized stakeholders in addition to the documentation group are:

Community reviewers; Reviewers responsible for handling non-documentation materials related to community interactions, contribution, and information. This includes materials like the o3de.org README.md and CONTRIBUTING files, in addition to blog posts and the website /community content.
Web development; Web developers must not touch documentation while documentation, blog teams, and the foundation may need to edit website code (such as shortcodes or templates for documentation to fix UX errors, or change information architecture.) Individual SIGs or the Foundation may review website changes where appropriate, but web developers must not review documentation changes.
The Open 3D Foundation; The Foundation itself should not only have a high level of authority to act upon the repository, but also must be the designated owner of certain materials such as any partner lists, logo images, or press releases they choose to post on o3de.org. They also must be able to respond to any urgent request related to o3de.org.

These groups should be named sensibly in accordance with O3DE group naming guidelines. We recommend:

Docs reviewers / maintainers: o3de/docs-reviewers and o3de/docs-maintainers - Existing groups that do not need a rename.
Community reviewers / maintainers: o3de/community-reviewers and o3de/community-maintainers - New groups analogous to o3de/docs-* but specifically for community and blog content.
Foundation representatives: o3de/lf - This is an existing group. If the Foundation would like to make website access more restrictive, they are welcome to request a change.
Website development: o3de/website-dev - A new group specifically for website maintenance.

Enforcement mechanism

The recommended enforcement mechanism is GitHub CODEOWNERS. This feature is already in use on o3de/o3de to designate feature ownership by SIG, and to ensure that reviewers are automatically assigned when appropriate.

GitHub CODEOWNERS file support exists explicitly to support the use case that this RFC is addressing.

Group ownership mappings in repository

The following tables describe which groups have merge privileges on which files. Files which the group has merge privileges to must participate in review, and each ownership group must establish appropriate review policies. For files with more than one group with merge permissions, one reviewer from each group with merge permissions (except the LF) should be required for merge.

Note: The Linux Foundation/O3DF group is only listed in this chart for files which they are required to review. Otherwise, they must have complete merge control over the entire repository, due to being the designated corporate owners of O3DE and their ownership of incident response.

Group	Merge permissions
`docs-reviewers`	`content/docs/*`
	`content/smoketest.md`
	`static/docs/*`
	`static/_redirects`
	`static/images/api-reference/*`
	`static/images/atom-guide/*`
	`static/images/community/*`
	`static/images/contribute/*`
	`static/images/contributing/*`
	`static/images/learning-guide/*`
	`static/images/release-notes/*`
	`static/images/shared/*`
	`static/images/tools-ui/*`
	`static/images/user-guide/*`
	`static/images/welcome-guide/*`
	`static/images/icons/*`
	`layouts/shortcodes/*`
	`layouts/docs/*`
	`layouts/partials/docs*`
`community-reviewers`	`content/blog/*`
	`content/community/*`
	`content/contribute/*`
	`content/docs/contributing/*`
	`static/images/blog/*`
	`static/images/community/*`
	`static/images/contribute/*`
	`static/images/contributing/*`
	`static/images/shared/*`
	`layouts/blog/*`
	`layouts/community/*`
	`layouts/contribute/*`
	`layouts/partials/blog/*`
	`layouts/partials/community/*`
	`layouts/partials/contribute/*`
	`layouts/partials/blog-display.html`
	`layouts/partials/css.html`
	`CONTRIBUTING`
	`README.md`
`website-dev`	`assets/*`
	`layouts/*`
	`content/search/*`
	`static/js/*`
	`config.toml`
	`Makefile`
	`package.json`
`foundation`	`content/download/*`
	`content/_index.md`
	`LICENSE-*`
	`_index.md`
	`netlify.toml`
	`static/apple-touch-icon-114x114.png`
	`static/apple-touch-icon-120x120.png`
	`static/apple-touch-icon-144x144.png`
	`static/apple-touch-icon-152x152.png`
	`static/apple-touch-icon-180x180.png`
	`static/apple-touch-icon-57x57.png`
	`static/apple-touch-icon-72x72.png`
	`static/apple-touch-icon-76x76.png`
	`static/apple-touch-icon.png`
	`static/favicon.ico`
	`static/img/*`
	`static/images/events/*`
	`static/images/home/*`

Required changes for Documentation & Community SIG

If this RFC is accepted, there will be some additional requirements for the SIG to take up as official business, and must involve representatives from each newly formed group to address the following concerns:

Requirements to become a "community" reviewer or maintainer, as an amendment to reviewers-maintainers.
Requirements to become a "web developer" reviewer or maintainer, as an amendment to reviewers-maintainers.
Clarification of ownership of specific website elements or features as owned by the SIG, Open 3D Foundation, or the web developer group. This should be proposed as an amendment to the current sig-docs-community charter.
Review guidelines and policies for each newly created group.

Technical considerations

The only technical consideration is the enforcement mechanism for access control. GitHub CODEOWNERS remains the most viable solution.

Scope of work

The scope of work is summarized best as:

Setting up the appropriate GitHub organizations or groups.
Creating and maintaining a CODEOWNERS file. This file will change if the group organization changes, or if the repository is restructured or changed in some way that requires adding or removing access control.
Amending SIG documents in a timely fashion.

All of these processes are more or less known quantities from an operational standpoint (1, 2) or have well-established processes if not exactly an understood scope of effort (3). A more or less complete description of what would be assigned via CODEOWNERS is contained within this RFC.

Are there any alternatives to this feature?

The only considered alternative at this time is to continue operating with a single reviewer and owner group, under the current charter and reviewer/maintainer roles. Alternate suggestions to the proposal outlined in this RFC are more than welcome.

Are there any open questions?

Press releases from Open 3D Foundation: An additional consideration is whether or not the Open 3D Foundation should publish press releases through the o3de.org website as opposed to o3d.foundation. Since press releases are published in the blog/ section, under SIG rules, they would require review from the community group. Relying on open source contributors for timely merging of press releases or coordinated information from the Foundation should be a concern.
Foundation representative access requirements. The foundation may require stricter access controls than only o3de/lf, or may have additional requests that they would submit outside of the RFC process as part of their ownership of the Open 3D Engine project.
Impending website redesign. Content may get reorganized or undergo further refinement of ownership during a website redesign. We will need to come up with an appropriate file mapping and possibly a further breakdown in partnership with web developers.

Proposed SIG-Docs meeting agenda for 2022-10-18

Meeting Details

Date/Time: October 18, 2022 @ 10:30am PST
Location: Discord SIG-Docs Voice Room
Moderator: Chanelle Mosquera
Note Taker: Name

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

What happened since the last meeting? - The creator of this issue is responsible for providing a brief summary here to be used as an update to start any important discussions.

Open action items

3 RFCs Proposed
- #43
- #61
- #64
2 RFCs Needed
- #49
- #50

Newly resolved items

✅

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Agenda item name - Presenter - Length of time
- Description of the item

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Review roles and signup

Description

We need to define the responsibilities and roles of our initial reviewer set, and encourage signups. These roles will not take effect until the launch.

Reviewer responsibilities

When you're conducting a review, you're acting as a representative of the Open 3D Engine project. Follow good etiquette and the Code of Conduct, and try to act in good faith.
Be kind and make it clear that suggestions are suggestions, unless they're clear violations of the Code of Conduct, project values, or style guide.
Be available during rotation. Rotation lengths will be determined by how many people are available on the reviewer list and we'll work to keep them as brief but contiguous as possible, but be prepared to make a time commitment during yours. We have no SLA, but want to keep contributions from going stale.

[?] And other rules...?

Proposed/available roles

Issue triage - Triage incoming issues. Our triage process isn't designed yet, but this role will mostly revolve around tagging issues correctly, closing invalid issues, and prompting issue filers for follow-up.
Content reviewer - Reviewer familiar with our writing style and focus, who works in an editorial capacity with the original author to make content suggestions that improve the quality of the PR. This can include copy suggestions, but an assigned copyeditor always has final say over those.
Technical reviewer - Developers who are willing to sign up to be on rotation to answer questions or provide detailed technical review for O3DF projects documented on the website (such as O3DE and Atom.) Technical reviewers may be contacted ad-hoc or assigned to review highly technical content.
Copyedit - Reviewers for style conformance and edit, and try to avoid higher-level (or developmental) edits. The copyeditor role is unique as it focuses only on a specific type of review, and will not be performed on every pull request.
Frontend reviewer - Reviewers/developers for website infrastructure and code.

Signing up

Leave a comment on this issue with the list of roles you would like to take. For technical reviewers, please also list your area of expertise.

Proposed SIG-Docs meeting agenda for 2023-01-10

Meeting Details

Date/Time: Month Date, Year @ 10:30 to 11:00 am PT
Location: Discord SIG-Docs Voice Room
Moderator: @chanmosq
Note Taker: @chanmosq

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

What happened since the last meeting? - The creator of this issue is responsible for providing a brief summary here to be used as an update to start any important discussions.

Open action items

Checkbox list of open action items from previous meetings. If these are closed before or during the meeting, mark them off.
...

Newly resolved items

✅ Unordered list of action items resolved since the last meeting.
✅ ...

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Agenda item name - Presenter - Length of time
- Description of the item
...

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Clarification on what documentation can be included in o3de.org

See topic #60 (comment)

Proposed SIG-Docs meeting agenda for 2022-09-27

Meeting Details

Date/Time: September 27, 2022 @ 1730 UTC / 10:30 pm PT
Location: Discord SIG-Docs Voice Room
Moderator: Chanelle Mosquera
Note Taker: TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

Upcoming 22.10.0 release

Our official policy for submissions until release is:

If it's a small fix to existing content published on o3de.org, submit your PR against main.
If it's documentation intended to be provided for the 22.10 release, such as any documentation for a new feature, replacement, or improvement, submit your PR against stabilization/22.10.
If you're writing something for future work that was not accepted into the o3de 22.10 stabilization, submit your PR against development.

[Updated] Important release dates for docs:

Release notes finalized (features + known issues) by 9/30/2022 (tandem with code freeze)
Versioned API reference generation: 9/30/2022

Open action items

Add code-owners.md and maintainer restrictions (@sptramer). #61
o3de/community#157

Newly resolved items

✅ #54

Initial Agenda

The pre-approved agenda for this meeting is as follows:

SIG Updates - @chanmosq
Agenda item name - Presenter - Length of time
- Description of the item
...

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed SIG-Docs meeting agenda for 2021-10-11

Meeting Details

Date/Time: October 11 @ 1PM PT / 2000 UTC
Location: In-person at O3DECon! - Tentatively break room (Platinum D) and Discord SIG-Docs Voice Room
Moderator: Stephen Tramer
Note Taker Chanelle Mosquera

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

o3de.org issues have now gone through an initial round of triage! This was done independently (sorry) so that we could start putting together the official committed roadmap.
The "Next Release" and "Future Release" milestones are being populated on GitHub. We also have independent milestone tracks for the website itself (content, features, bug fixes, &c.)

Open action items

@spotzz - Onboarding for contributors to o3de.org - how to make your first contributions, etc. (meta info on contributing)
@sptramer - Official taxonomy and structure
- Information that can be delivered to the community through a wiki page or something?
@sptramer - Schedule SIG triage meetings
@sptramer - Complete "Next Release" roadmap for docs

Newly resolved items

✅ Cleared up the action item backlog from previous meetings.

Initial Agenda

The pre-approved agenda for this meeting is as follows:

SIG Updates - Stephen Tramer - 10m
- All the news that's fit to print. Further updates closer to (and at) the meeting.

The remaining 50 minutes of this meeting are for community agenda items. Please remember to propose and vote!

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Draft new reviewer guidelines: docs-reviewer, community-reviewer, web-reviewer, and baseline tech reviewer rules/template

As part of accepting #61, we need clearer guidance around which types of review roles are available, what the qualifications are, and where you can go for more information. Part of this will be involved in the messaging (#61) in collaboration with other SIGs, possibly filed as additional RFCs under the provision that the current proposal is the working model for right now.

Tasks

Draft any new docs reviewer, community reviewer, and web reviewer guidelines needed.
Draft baseline requirements for tech reviewers, and socialize to other SIGs. SIGs are allowed to modify this baseline (including exemptions from some of our rules, with approval).

Message acceptance of RFC #61

Since #61 has been officially accepted and requires some infrastructure, permissions changes, and additional descriptions of reviewer roles, these need to be messaged to other SIGs. Checklist for messaging:

sig-chairs mailing list
Discord #sig-all
Impactful change message

Proposed SIG-Docs meeting agenda for 2022-06-14

Meeting Details

Date/Time: June 14, 2022 @ 1800 UTC / 11:00am PT1800 UTC / 11:00am PT
Location: Discord SIG-Docs Voice Room
Moderator: @FiniteStateGit
Note Taker: @FiniteStateGit

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

Refer to the following links for the latest google crawler coverage reports:
#42 (comment)

Open action items

We need somebody to start working on RFCs for automated submission checks, so that we can avoid filing regular broken link issues.
It is recommend we remove the https://docs.o3de.org/ subdomain and just use https://o3de.org/docs - also it may be that the way we are using/redirecting our www. subdomain is causing google to treat it differently - might we worth examining the DNS record to check for anomalies.
- Double check source for any links to docs.o3de.org.
Announce sig-docs-elections 6/28.
Website refresh: Nicole Huesman[LF] will approach sig-docs and sig-ui-ux for comment on the proposal this week.

Previous meeting's open action items:
#41

Open RFC's

#43
#40

Agenda Items

From @micronAMZN :
https://image-compare-viewer.netlify.app/
Sig needs a process for accepting 3P packages to Netlify build.

From @aFinchy:
https://docs.google.com/document/d/1Uuz0mvEOMcXBAzcJpop7EqFGzbU2nhXK52wG_c_ls08/edit
Requests sig-docs-community prepare our contribution similar to the example.

Proposed SIG-Docs meeting agenda for 2021-09-22

Meeting Details

Date/Time: September 22, 2021 @ 1600 UTC / 9AM PT
Location: Discord SIG-Docs Voice Room
Moderator: Stephen Tramer
Note Taker TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

What happened since the last meeting? - The creator of this issue is responsible for providing a brief summary here to be used as an update to start any important discussions.

Open action items

@sptramer - Resolve writing style PR checklist: o3de/o3de.org#563
SIG - Final charter review
- RFC Issue
- Existing proposed changes
- Closes 2021-09-29
@spotzz - Onboarding for contributors to o3de.org - how to make your first contributions, etc. (meta info on contributing)
@sptramer - Official taxonomy and structure
- Information that can be delivered to the community through a wiki page or something?
@sptramer - Offload Discord management to #sig-operations
SIG - Blog posts o3de/o3de.org#749
- Closes 2021-09-24
@sptramer - Schedule SIG triage meetings

Open Proposals

@FiniteStateGit - #12

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Open Action Item resolution - Stephen Tramer - 10m
- Go through the list of open action items and either resolve them or set due dates to close feedback by.
Contributor Requirements and Roles - Stephen Tramer - 10m
- There are now contributor requirements which will need to be amended for information on how to become a docs contributor. We have a list of available roles which we will make official as part of this.
Coordinating with the community - Stephen Tramer / Finite_State - 15m
- There are now enough potential contributors for major content changes that we need to start organizing good communication about ongoing work and how we plan and demonstrate the O3DE Docs roadmap (O3DE Roadmap is already available.). Exact details to come.
Proposed project - Lua Documentation - Finite_State - 10m
- TBD (proposer please amend with details)

The remainder of time is available for community-proposed agenda items.

Agenda voting will remain open until 9/22/2021 12AM PT

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed SIG-Docs meeting agenda for 2022-04-26

Meeting Details

Date/Time: April 26th, 2022 @ 1800 UTC / 11AM PT
Location: Discord SIG-Docs Voice Room
Moderator: Stephen Tramer
Note Taker: TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

This meeting is being held explicitly to handle the 22.05.0 release, but additional agenda items can be accepted for discussion since it is a SIG meeting!

SIG Updates

Release management

Open action items

Election alignment updates (@sptramer)
Recorded target user definition + rationale (@sptramer)
Process RFC: Maintainer restrictions on o3de.org (@sptramer)
Feature differentiation blog (JT)
New SIG requirement: Owners of game/art/sample (non-docs) content. (@sptramer to raise to TSC)
Handling collaboration between partners (re: #38 (comment)) (@sptramer to raise to TSC and LF)

Open RFCs

o3de/sig-release#50

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Release updates - Stephen Tramer - 20m
- Discuss anything and everything relevant to the release that needs representation from sig-docs-community.
Copy reviewer pool - Stephen Tramer - 10m
- Discuss the creation of a copyedit reviewer role, and propose the promotion of @paucom and @JwGedit to the role of "reviewer" within it.
Use of checkboxes on PRs - Stephen Tramer - 10m
- Currently the 4 checkboxes on the PR template cause some confusion with submitters, who are unsure if they check them (to agree) or the reviewer checks them (to pass the PR). Take some time to discuss how to address this and pass a vote in the SIG for future action (or policy.)

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

SIG Reviewer/Maintainer Nomination

Nomination Guidelines

Documentation reviewer

6+ documentation contributions merged to o3de.org or O3DE
2+ Reviewer or Maintainers of the Documentation and Community SIG.

Maintaining status: 4+ Pull Requests reviewed per month.

Reviewer/Maintainer Nomination

Fill out the template below including nominee GitHub user name, desired role and personal GitHub profile

I would like to nominate: @FiniteStateGit to become a Docs Reviewer on behalf of sig-docs-community. I verify that they have fulfilled the prerequisites for this role.

Nominee's GitHub Profile https://github.com/FiniteStateGit

Reviewers & Maintainers that support this nomination should comment in this issue.

Update o3de.org/docs reviewer process to require 1 docs-reviewer and 1 technical-reviewer

We should change the merge permissions for the main branch in o3de/o3de.org repo, requiring that 1 docs-reviewer and 1 technical reviewer approves the PR before it can be merged. This ensures that the appropriate people review incoming PRs to the o3de.org repo.

Action items

Complete an RFC denoting this change (#70)
Document the process to become a technical-reviewer

Blocked by

Updates to CODEOWNERS file, as indicated by #61

Post action items

Communicate with all SIGs of this change
Growing the technical-reviewers GitHub team

RFC: SIG Charter Review

Summary

This issue is for a formal review of the SIG Charter after discussion in the 21-08-27 SIG meeting. There is an open pull request, PR
#6, which will be used to collect changes that result from this discussion. Please review the D&C SIG Charter and provide the feedback on this issue.

Providing feedback

If you're providing general feedback on the SIG rather than a specific line or element in the charter, provide as much information and context as you need to.
If you're responding to specific text or items in the SIG charter itself, please include the context for the part of the document you're referring to in a quote (markdown > leader).

Proposed SIG-Docs meeting agenda for 2022-11-08

Meeting Details

Date/Time: November 8, 2022 @ 10:30 am PT
Location: Discord SIG-Docs Voice Room
Moderator: @chanmosq
Note Taker: @sptramer

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

Agenda

The pre-approved agenda for this meeting is as follows:

SIG Updates
See the remaining agenda items in the comments below.

SIG Updates

What happened since the last meeting?

The last meeting took place onsite at O3DCon 2022. There we discussed some open RFCs, the discussions are placed in the RFC issues themselves. No RFCs have been accepted since then, but some activity from reviewers has occurred.
From TSC, discussions about general planning across all SIGs.
- April 2023 Release Planning
- All SIGs are putting together a roadmap. (One of our agenda items to discuss.)
From TSC, o3de/o3de-extras repository will continue to grow and may require maintenance from all sigs.

Open action items

See https://github.com/orgs/o3de/projects/15/views/1.

Newly resolved items

The following RFCs were accepted during the meeting:

#61
#64

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

SIG Reviewer/Maintainer Nomination: @micronAMZN

Documentation maintainer

Has been a Reviewer for 2+ months
8+ reviewed Pull Requests in the previous 2 months
2+ D&C SIG Maintainers who support promotion.

Maintaining status: 8+ Pull Requests reviewed per month.

Reviewer/Maintainer Nomination

Fill out the template below including nominee GitHub user name, desired role and personal GitHub profile

I would like to nominate: @micronAMZN to become a Maintainer on behalf of sig-docs-community. I verify that they have fulfilled the prerequisites for this role.

NOTE: Mike has been unofficially performing in the role of reviewer for 6+ months since the launch of O3DE.

Nominee's GitHub Profile: @micronAMZN

Reviewers & Maintainers that support this nomination should comment in this issue.

RFC: Docs Versioning

Summary

This project is a follow up to the RFC for the separation of main and development branches that was implemented earlier this year.

As O3F continues to release versions of the O3DE product and moves towards long term support (LTS) of these versions, it has become clear that the o3de.org website needs a docs versioning strategy to solve the following problems:

Readers who have installed a specific release of O3DE want docs that reflect the state of O3DE in that version. When that version moves into LTS and is no longer the current release version, we will need to preserve that version of the docs, separate from the newer docs.
As engineers make changes to the O3DE development branch, they document new features and updates in the development branch of the website. These engineers and other early adopters want a convenient way to view these new docs.
During the multi-week stabilization for a new release, the upcoming docs for that release should be frozen while work continues separately in the development branch.
We may want search engines to return results only from the latest released version of the engine, instead of older versions or the development version.

What is the relevance of this feature?

Why is this important?

For the purpose of LTS, we want to provide and preserve multiple doc version sets.

What are the use cases?

Readers want to easily browse and search docs that are relevant to the version they have installed or have built.

What will it do once completed?

Readers can use a docs version selector mechanism (e.g. drop-down selector box) to switch to the doc version set of interest to them. The version remains selected as they navigate through any of the guides and topics. Ideally, their browser remembers the last selected version for future visits (e.g. through the use of cookies).

What are the advantages of the feature?

Multiple docs version sets are readily available to O3DE users, including some topics that are "hot off the press" in the development branch, available months before their official release.
Switching between any of the docs version sets to browse and search the versions that interest you becomes easy, without having to manually type in and bookmark all the various URLs.
Older docs version sets remain available, even after new releases are published.

What are the disadvantages of the feature?

Some amount of additional website maintenance is expected every time a new docs version set becomes available.
Preserving multiple branches takes up GitHub repo space. This has not posed a problem yet, and it's not clear it ever will.
- GitHub, for example, recommends that repos be kept under 5 GB, but only for performance reasons. Using the git-sizer tool on the o3de.org repo, we appear to be healthy and within reasonable limits overall.
- Netlify has no documented limit on the number of branches it will publish. (Refer to Netlify docs on branches and deploys and pricing and features.)
- However, if this does ever become a problem, we have solutions such as Git LFS that could be used for large files such as images and videos, and which could be implemented independently from the versioning solution proposed here.

Feature design description

The default website experience (without any cookies set), as published from the main branch of the o3de.org repo, will continue to reflect the docs version set that pertains to the latest release version of O3DE. Additional doc set versions, pertaining to other branches including development, staging, and earlier releases of O3DE, will be available through a version selector that's visible on all pages that fall under o3de.org/docs.

The version selector is not needed on pages outside of this directory structure, since versioning is either not needed (e.g. no need to view earlier home and community pages), or will have unique versioning rules (e.g. obtaining earlier downloads).

When a version is selected, the URL for that version will be opened. Our static site generator, Netlify, can publish any branch that we want. Each published branch will be available using a specific URL. As part of the version selection process, a functional cookie will be set to preserve the selected version for future visits by the user on that web browser.

When readers view versions of the docs that are NOT from the default version, an appropriate banner will appear at the top of every page alerting them to this fact.

Technical considerations

Branch dynamics

Docs contributors will need to be informed about the process and procedure for submitting PRs in this versioned environment.

Contributors to the development branch of the source repo will typically target their PRs to the development branch of the docs repo. (This pattern is in place today.)
At the start of stabilization for the next release, a staging branch will be created or updated. It will contain all commits/changes intended for the next release, and will be included in the list of published branches in Netlify and available versions in the version selector.
As part of a release, the following occurs:
- A new branch is created from main to reflect the previous version.
- The new branch is added to the list of published branches in Netlify.
- Main is updated from staging.
- A PR is created to update the static API docs in main.
Updates to docs branches for earlier versions of O3DE can be made on a case-by-case basis, as LTS requires.

Branch URL

Currently, we publish docs from main and development branches. Main is configured as the "production branch" in Netlify, which allows us to assign o3de.org as its URL. However, the URL for non-production branch deploys, such as development, is not as intuitive by default. For example, the URL for the development doc set is currently development--o3deorg.netlify.app/.

A more elegant solution supported by Netlify is to use branch subdomains, which would allow us to publish to simple subdomains of o3de.org, such as development.o3de.org. (We might even want to use a shorter URL like dev.o3de.org.)

However, this requires additional configuration. The recommended configuration requires the use of Netlify DNS. There is no additional cost for this feature, and setting up new branches is virtually hassle free, touted by Netlify as "single click setup". However it requires some degree of trust and authority to be given to Netlify in order for them to manage the SSL cert registration and renewal for all published branches.

There is another configuration option, but it requires a lot more manual work to set up a new branch. According to a Netlify article on using Netlify's branch deploy feature without Netlify DNS, this includes creating the DNS record to point to the Netlify branch record and contacting Netlify technical support to provision an updated SSL certificate.

🟨 We will need to work with O3F and Netlify to figure out which option can be used. 🟨

Version selector

The version selector will need to be populated from an approved list of branches. We should use short names (aliases) in the version selector box, such as "Current release", "22.05", "Staging", and "Development". Each alias will map to a URL. Note that Netlify deploy contexts might help with the implementation of this. Using deploy contexts, you can override options on a per-branch basis, including build commands and environment variables.

In regards to setting a cookie, any time a cookie is used by a website, it is important to consider user privacy laws such as GDPR and whether or not a user interface needs to be provided for clearing the cookie. According to a Cookiebot article on this topic:

| The EU cookie law (ePrivacy Directive) covers any kind of technology that process personal data from users online and uses “cookies” as an umbrella term. However, it also clearly states that the cookies deemed to be strictly necessary for the most basic functions of a website are exempt from the prior consent requirement (such as cookies that manage the contents of a user’s shopping cart on a web shop).

Scope of work

The following work has been identified:

Add a version selector box to the design of all pages that will publish under o3de.org/docs. This includes content from /content/docs and /static/docs. Selecting a value in the selector box should set a cookie and load the new URL.
Implement a design that can populate the version selector box.
Update robots.txt as necessary to exclude all doc versions except latest (main).
Work with O3F infrastructure to either set up Netlify DNS or get DNS records created and SSL certs provisioned for the subdomain branches.
Update the documentation on contributing to docs to explain the branch dynamics rules outlined earlier.

Include an estimation of the scope of work, so the SIG can determine if it can be reduced to a single issue (or small set of issues) an individual can perform, or if it needs to be a coordinated effort as an official SIG project.

Are there any alternatives to this feature?

An alternative is to do nothing to the website design and continue creating branches in GitHub. For versions of the docs other than the current release, we could publish a list of their URLs on a page somewhere. However, this is unconventional for game engine documentation, and could be seen as unprofessional.

Are there any open questions?

Will O3F infrastructure grant the appropriate DNS rights to Netlify to support the use of Netlify DNS and make creating branch subdomains with intuitive URLs a simple one-click process?
Who from O3F infrastructure will work with the documentation SIG in a timely fashion to implement the DNS-related portions of the solution?
How will this affect the new website design, if at all?

SIG-Docs-Community 11/30 release notes

Please fill any info related to the below for the 11/30 release notes: Note this has a due date of Friday Nov 12th, 2021

Features
Bug fixes (GHI list if possible)
Deprecations
Known issues

Remove docs.o3de.org subdomain

The docs.o3de.org subdomain was created at the start of O3DE, and it is no longer used. The official domain is now o3de.org/docs. We must remove the docs.o3de.org domain and any links that point to it. To prevent any misdirects, docs.o3de.org should redirect to o3de.org/docs.

Proposed SIG-Docs meeting agenda for 2021-08-27

Final agenda

Meeting Details

Date/Time: August 27, 2021 @ 6:00PM UTC / 11:00AM PT
Location: Discord SIG-Docs Voice Room
Facilitator: Stephen Tramer
Note Taker: TBD - Volunteers welcome

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

This is the first public meeting to be held by sig-docs-community after O3DE launch!

Open action items

SIG - Resolve writing style PR checklist o3de/o3de.org#563

Final Agenda

The agenda for this meeting is as follows:

Scope of SIG and charter - Stephen Tramer - 15m
- In pre-release there were plenty of discussions about the SIG charter and scope. Now we need more community feedback, especially as the scope of this SIG is relatively large and requires a lot of collaboration with its mission as stated! Please read the charter before the meeting if you want to participate in the discussion.
Blog publishing steps - Liv Erickson - 10m
- I'd like to propose a discussion for next steps related to how community members can propose topics for new blog content that they are authoring. This could include identifying an owner to submit an RFC for the process, and identifying next steps on coordinating with the marketing committee to define a process. I have been working on a roadmap blog post from the AWS team that we can use as a test for the new process.
Pull request template review - Stephen Tramer - 10m
- Close the open business item regarding o3de/o3de.org#563, and/or assign official reviewers to represent the interests of the SIG in resolving the item.
Meeting cadence - Stephen Tramer - 5m
- How often should the SIG meet? Do we want to stagger meeting times in time-zone-friendly manners?

SIG Reviewer/Maintainer Nomination: @willihay

Documentation maintainer

Has been a Reviewer for 2+ months
8+ reviewed Pull Requests in the previous 2 months
2+ D&C SIG Maintainers who support promotion.

Maintaining status: 8+ Pull Requests reviewed per month.

Reviewer/Maintainer Nomination

Fill out the template below including nominee GitHub user name, desired role and personal GitHub profile

I would like to nominate: @willihay to become a Maintainer on behalf of sig-docs-community. I verify that they have fulfilled the prerequisites for this role.

NOTE: Will has unofficially been acting as a reviewer since the launch of O3DE 6+ months ago.

Nominee's GitHub Profile: @willihay

Reviewers & Maintainers that support this nomination should comment in this issue.

Proposed SIG-Docs meeting agenda for 2023-01-24

Meeting Details

Date/Time: January 24, 2023 @ 10:30 am PT
Location: Discord SIG-Docs Voice Room
Moderator: Name
Note Taker: Name

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

What happened since the last meeting? - The creator of this issue is responsible for providing a brief summary here to be used as an update to start any important discussions.

Open action items

Checkbox list of open action items from previous meetings. If these are closed before or during the meeting, mark them off.
...

Newly resolved items

✅ Unordered list of action items resolved since the last meeting.
✅ ...

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Agenda item name - Presenter - Length of time
- Description of the item
...

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed RFC: Engine Developer Guide

Closed in favor of using the PR submission mechanism; #73

Proposed SIG-Docs meeting agenda for 2022-09-13

Meeting Details

Date/Time: September 13, 2022 @ 1730 UTC / 10:30am PT
Location: Discord SIG-Docs Voice Room
Moderator: @sptramer, @chanmosq, @aFinchy
Note Taker: @FiniteStateGit

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

c/o @willihay

The nomination period is now closed. We have two nominations for the two chair positions, therefore no election is necessary. Congratulations to @hanmosq [Amazon] and @aFinchy [Amazon, Finch Studio], our next co-chairs! They will formally begin serving in September, at the start of the first sig-docs-community meeting.

c/o @sptramer

Docs stabilization has been cut: Use the stabilization/22.10 branch for any documentation which is targeted for the 22.10 release. Our official policy for submissions until release is:

If it's a small fix to existing content published on o3de.org, submit your PR against main.
If it's documentation intended to be provided for the 22.10 release, such as any documentation for a new feature, replacement, or improvement, submit your PR against stabilization/22.10.
If you're writing something for future work that was not accepted into the o3de 22.10 stabilization, submit your PR against development.

Important release dates for docs:

Release notes finalized (features + known issues) by 9/27/2022 (tandem with code freeze)
Versioned API reference generation: 9/28/2022

Open action items

Delete stale branches.
Add code-owners.md and maintainer restrictions (@sptramer).
Decide if and where to place target user definitions.
Add information on contributing to O3DE and the SIG on readme: https://docs.google.com/document/d/1Uuz0mvEOMcXBAzcJpop7EqFGzbU2nhXK52wG_c_ls08/edit.
Remove docs subdomain from o3de.org.
Add automated submission checks (broken links, spelling, style issues).
Incorporate feedback into SIG docs feature grid (@FiniteStateGit). #40

Newly resolved items

✅ Stabilization branch for 22.10 release created.

Initial Agenda

The pre-approved agenda for this meeting is as follows:

Sig-docs-community chair handoff - @sptramer

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed SIG-Docs meeting agenda for 2022-04-12

Meeting Details

Date/Time: April 12th, 2022 @ 1800 UTC / 11AM PT
Location: Discord SIG-Docs Voice Room
Moderator: Stephen Tramer
Note Taker: TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

What happened since the last meeting?

main / development split in action - public contributor guidance ETA this week. (@Stramer)
Preparation for release 22.05.0
- Proposed: Additional SIG meeting on 4/26 for release preparation and to handle any additional business.
Mid-year elections
- Proposed: Initial chair term was for 1yr, which is a mismatch with the other SIGs (chairs serve a 6-month term.) Would like to hold mid-year elections for Chair and Co-Chair in alignment with the other SIGs.

Initial Agenda

The pre-approved agenda for this meeting is as follows:

SIG update - Stephen Tramer - 10m
Projects update - Stephen Tramer - 5m
- Requested by TSC: Feature grid RFC (see o3de/o3de#6821)
Target user definition - Stephen Tramer - 10m. We should be setting the target user from the perspective of the documentation and community SIG, so that we can start work on progressing towards...
Content level definitions - Stephen Tramer - 15m. One ongoing problem the SIG has encountered is a correct understanding of our required quality level for acceptance. With the split of main and development, this may become even more complicated (allowing a lower quality bar for development makes sense for high-velocity documentation.) The SIG needs to start discussing what we see as our "minimum quality bar".

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed RFC: Documentation reporting on the Feature Grid

Summary:

Documentation health in each important feature area needs to be reported in some way for the O3DE feature grid (link). This RFC covers the column extensions and terminology used by sig-docs-community for reporting on the state of documentation in a way that aligns with how SIGs report on the state of their features to the TSC, TAC, and Governing Board.

What is the motivation for this suggestion?

Currently, the TSC, TAC, and Governing Board only are informed of the engineering state of the product. They should also be aware of the level of documentation available to users for each feature. For many features documentation is considered critical to user success, and so the lack of documentation for a fully complete feature may still render it difficult or impossible to use for customers.

If this suggestion is not implemented, sig-docs-community will find another method to establish conveying information on product health to the TSC, TAC, and Governing Board.

Suggestion design description:

Feature grid extension

The following three columns are added to the feature grid: Conceptual Docs, Tutorials, Samples. These columns are defined as follows:

Conceptual docs: Descriptions of features, and how the features operate in a user-facing manner. Does not necessarily include engineering or low-level documentation (low-level is feature-relative; Gem development or core engine programming will always require that even the highest-level content is complex.) This is about docs that explain the concepts behind the feature, and often cross-reference or relate to other documentation about the engine.
Tutorials: Examples, samples, and walkthroughs designed to help users with the specified feature. This can include video series available from O3DE on YouTube, projects designed with the intent for users to learn and explore a feature (some crossover with samples), or written instructions or guidance walking a user through a common or example scenario.
Samples: Code or existing projects, assets, and content which can assist a user in using the feature. Samples include things like code samples, example projects, demos (such as MultiplayerStarterProject), and reference assets or templates.

Removal of current docs info on Feature Grid

We suggest removing the “Docs link” column; for some features this may be misleading, or even lead them into a section of the documentation that doesn’t appear relevant (even if it is.) This is a consequence of the current information architecture of the o3de.org (http://o3de.org/) website, and the lack of ability to set up a full subgrid for navigation underneath a single feature. The column can be re-added with an appropriate RFC to account for these issues.

New documentation column scores

Since the definitions used by sig-docs-community to grade content are different from the definitions that can be used to describe code health, we require the following to be added for our columns only. Our completeness grades need to be more like a “quality” grade - the work of documentation is never done.

N/A: Documentation is not required and does not need to report on any information for this specific feature.
None: Documentation is required, but none is available. This includes topics where documentation contains only deprecated or removed features and was not updated.
Minimum: Documentation exists, but is only of the minimum amount to have been determined to make a user “successful” with the feature. Content may be of low quality, but is guaranteed to meet the minimum quality bar for accepting contributions set by sig-docs-community.
Partial: A feature is approximately 50% or more documented at the minimum quality bar.
Good: A feature is approximately 75% or more documented, and the quality is above the minimum bar.
Excellent: A feature is 90% or more documented, and the quality is well above the minimum bar.

Explicitly not in this RFC

API reference coverage levels: API reference generation is an ongoing topic in the SIG, and needs RFCs to establish a process and convention. Currently our API reference is generated manually, and an automated process will allow for some form of red-yellow-green coverage dashboard for overall API health for each SIG.
Script Canvas, Component, Lua, and some other reference: These are also all being investigated for automated reference generation, and the process of doing so will set up automation and coverage dashboard reporting in the same manner as API reference.
Subdividing docs categories or supplying links to content: This requires an entirely different grid of information well beyond the current feature grid, and is more of a site navigation feature. As described in the section on removing the “docs link” column, a lack of a subgrid prevents this from being particularly useful at this time.

What are the advantages of the suggestion?

Allows engineering teams to make informed decisions about feature upgrade and improvement paths by looking at the grid; A downgrade in a docs score for that feature means that the change would be significantly user-impacting, even if there is lower engineer impact.
Guarantees that sig-docs-community and all engineering SIGs are aligned regarding what they report on in terms of a feature, and what the state of that feature is.

What are the disadvantages of the suggestion?

Because feature grids are submitted per-SIG, SIGs will need to evaluate the state of the feature documentation prior to submitting them to the feature grid repository. SIGs would need to assume the responsibility for this evaluation or coordinate with members of sig-docs-community. Alternatively, sig-docs-community would need to amend each SIG’s feature grid after it has been submitted to the feature grid repository.
The proposed changes do not guarantee that the entirety of O3DE documentation is evaluated. Fundamental, peripheral, or cross-cutting topics may not be listed among a SIGs features.
The proposed scoring system manages to define gradations in document quality but may be difficult to uniformly implement across features because of its inherent subjectivity. For some features, defining a minimal set of use-cases may be difficult.

How will this work within the O3DE project?

As a first step, the feature state form would be updated with the columns and scoring selection outlined by this RFC.
Currently the feature grid is updated and released for each major release. We propose that SIGs evaluate documentation for their features after code freeze occurs and after any relevant feature documentation has been submitted to the o3de.org (http://o3de.org/) repository for inclusion in a release.
We propose that individual SIGs take primary responsibility for reviewing and updating the documentation sections of their respective feature grids. We reason that SIGs will be the best judge of the sufficiency of a feature’s coverage in documentation, which is the predominant component of documentation scoring.
Sig-docs-community will provide support, consultation, and feedback when requested.

Are there any alternatives to this suggestion?

Consideration was given to a solution wherein sig-docs-community submits its own feature grid independent of other SIGs. Existing column and scoring options were not adequate to detail the state of documentations. While this implementation did allow freedom to list alternative and additional features than those listed by other SIGs, it conflicted with columns (and their interpretation) of the feature grids already submitted by the SIGs. Users would need to navigate to two different, disjointed rows per-feature to review the state of engineering and documentation efforts. Refer to prior discussion by sig-docs-community: #40.
Keep the present feature grid design, which cannot adequately capture the state of feature documentation with regards to the different types of documentation the product requires.

What is the strategy for adoption?

The README for the feature state form is updated (https://github.com/o3de/community/tree/main/features#readme) with descriptions of new columns and the criteria for scoring them. Criteria for scoring are as described in “Column Scores”.
The proposed changes are implemented on the feature state form ( https://o3de.github.io/community/features/form.html).
After completely listing each feature included in a release, each SIG, independently or in conjunction with sig-docs-community, evaluates and scores relevant documentation for those features. SIG feature grids are updated and uploaded, as necessary, to the feature grid repository.

Asset sharing platform

A lot of engines and tools have the added benefit of some kind of an asset library, whether it's done via the browser or a custom user interface. Added documentation regarding the authoring of shared assets could home in on such a feature.

Maybe individual creators could have profile pages similar to how one would through itch.io or alternatively have some kind of a decentralized server based solution. If for example someone wants to share something directly via a link through a Discord, they could package things up through some kind of a tool for this purpose.

Proposed RFC: Introduce developer documentation for the Action Manager system

Feature: Action Manager developer documentation

The Action Manager is a new system that replaces the existing architecture(s) used to define menus, toolbars, hotkeys and overall editor actions in O3DE. We want to introduce proper developer documentation to enable existing and new systems, both core to the editor or added via Gems, to adopt the system and thus standardize the user experience across all the different parts of the Editor.

More details about this feature: o3de/sig-content#51
(The RFC goes over some user customization functionality at the end that was not included in the current MVP, but gives a good overview of the scope)

What is the relevance of this feature?

By providing a complete developer documentation, we aim to facilitate adoption which will enhance the extensibility of the Editor overall.

What are the advantages of the feature?

Developers can adopt this new framework more easily than having to manually search the codebase for existing integrations;
Best practices and expectations can be explicitly stated, reducing review times for PRs;
The reasoning behind the architecture can be detailed to enable future developments to follow the same mindset and standards.

Scope of work

The Action Manager system is also comprised of additional sub-systems that manage Menus, ToolBars and Hotkeys.
Documentation should likely include

API references;
Architecture Overview;
Startup guide for developers creating new systems;
Migration guide for developers reworking existing systems to adopt the framework.

I am planning to dedicate the time necessary to write down the bulk of this documentation; the support that I would need from sig-docs-community is related to the style and hierarchy of the pages/topics to conform with the rest of the docs.

Proposed SIG-Docs meeting agenda for 2022-05-17

Meeting Details

Date/Time: May 17th, 2022 @ 1800 UTC / 11:00am PT
Location: Discord SIG-Docs Voice Room
Moderator: Stephen Tramer
Note Taker: TBD

The SIG-Docs Meetings contains the history past calls, including a link to the agenda, recording, notes, and resources.

SIG Updates

What happened since the last meeting? - The creator of this issue is responsible for providing a brief summary here to be used as an update to start any important discussions.

Open action items

Election alignment updates (@sptramer)
Recorded target user definition + rationale (@sptramer)
Process RFC: Maintainer restrictions on o3de.org (@sptramer)
Feature differentiation blog (JT)
New SIG requirement: Owners of game/art/sample (non-docs) content. (@sptramer to raise to TSC)
Handling collaboration between partners (re: #38 (comment)) (@sptramer to raise to TSC and LF)

Open RFCs

Newly resolved items

None

Initial Agenda

The pre-approved agenda for this meeting is as follows:

SIG updates - 10m - Stephen Tramer
- Ongoing work to define tone, voice, and minimum viable content
- Upcoming presentation from Red Hat on style
Agenda items - 50m

Suggesting and voting on agenda items

Our community is welcome to suggest and vote on agenda items. If you suggest an item you need to have a designated presenter (normally the issue filer), but any community member can vote and isn't required to attend meetings or even participate in further discussion. If you think something is a good idea to discuss for the O3DE community, please upvote!

👍 reactions to proposed agenda items are counted as YEA votes for taking up discussion, and 👎 as NAY. Votes on items don't determine the final agenda, but do influence it and are strongly taken into consideration as a representation of what the O3DE community wants to see from the project.

Agenda item format

If you leave a comment on this issue to propose an agenda item, please use the following format:

**Topic**: The topic you'll be presenting on
**Presenter**: Who will present (may be a team name or TBD)
**Length of time**: Estimate the amount of time you believe discussion will take. This should not be more than 15 minutes without SIG approval.

Include a description of your topic. Make sure to link to any supplementary materials such as RFCs, forum discussions, issues, etc.

Remember to add the 👍 and 👎 reactions manually, so they appear and are obvious to voters!

Proposed RFC: Separate `main` and `development` branches for versioning

Separating `main` and `development` website branches

During the 2022-02-08 SIG meeting we discussed two ongoing issues: Website versioning (represented as an official SIG project) and the need to currently keep in-flight documentation for "next release" off of the website, while also accessible to users. There have been some stop-gap efforts such as using the o3de wiki, which fragments our documentation.

This proposal is to prepare for full website versioning by effectively beginning a separation between "last binary release" (main) and "in-flight work" (development). While there are issues with how features are selected for release, patch backporting, etc. we expect these problems to be discussed as part of the full website versioning proposal. This is an initial stage to enable minimal separation of the two workflows and enable our future versioning.

What is the relevance of this feature?

There are two primary issues which prompted the proposal for separating development and main:

Users may get unreliable information, as we expect at this point many of them will be using at minimum the 2111.2 QoL update, and in-flight feature documentation is not representative of this release - even if there are only minor adjustments to existing features, if they are updated for dev, any user running a binary (or built from git branch) release will likely encounter issues. Keeping main (and the live site) locked to "latest release" until a full versioning strategy is in place will be helpful to users.
Developers have difficulty getting work for in-flight features merged to main. This is because of the high standard of quality that we try to maintain on live documentation, especially for new documentation. We want to encourage engineer contributions as the subject matter experts on reference and in-depth feature knowledge, and a higher-velocity, lower-stabilization development branch enables this.

What are the advantages of the feature?

Separation of in-flight from released features, as described above.
- Better user experience (documentation is "locked to release")
- Better developer experience (developers have a lower bar of acceptance for in-flight feature docs; They aren't required to worry about "sitting on" docs until code is ready for a versioned release; They will be able to accept longer turn-around times in edit; It will be clearer where "bug fix" docs vs. "new feature" docs go)
Preparation for versioning strategy: A versioning strategy will include a plan for documenting o3de/development, which may be a different workflow than proposed in this RFC; However, it's expected that any versioning strategy will work off of git tags, branches, or another mechanism that enables easy versioning automation. The branch separation strategy also prepares our audience for the migration to a versioned website and will theoretically make the versioning even easier.

What are the disadvantages of the feature?

Representation of velocity. In the design description the practical infrastructure concerns lay this out, but until there is inline versioning on the website for docs in some capacity, we will want to stage main and development separately. This will put development on a subdomain, such as dev.o3de.org - separating visibility into in-flight features from released features. This is intentional and by design, as outlined in the proposal. The philosophical argument is that user experience on docs matters, and unless we have actionable telemetry, we must make assumptions on whether users are operating off development or a versioned release. Activity in Discord and on forums at this time is anecdata that many users are sticking with versioned releases.
- MITIGATION: Actively directing users reading versioned documentation (main, o3de.org) to dev docs (development, dev.o3de.org) and vice-versa, at minimum on the /docs landing page index (and presumably the indexes of each major guide.)
Confusion in migration to full versioning. Full versioning of the website will require UI/UX integrations and potentially additional build infrastructure, and should not rely on subdomains. This proposal is for a stopgap measure to address what we see as an urgent need, as there is no current timeline for the implementation of website versioning. As a consequence, the technical design is as minimalist as possible.
- MITIGATION: This is why 301 PERMANENTLY MOVED exists as an HTTP response status code. dev.o3de.org will redirect to the appropriate versioned documentation for development when full versioning is in place.

Feature design description

GitHub o3de.org changes

The creation of a development branch. The current state of main will be considered to be representative of 2111.2, although it has been updated with new features since that release.

Netlify changes

We would be publishing both main (as our production site) and development (as dev.o3de.org). See the Netlify branch publishing documentation. There is infrastructure support for supporting this feature.

Global search indexing

We should determine if site indexing should be disabled for dev.o3de.org, at the risk of making in-flight feature docs less discoverable. Keeping it enabled will pollute search results however, and likely lead to the same problem we experience now (users seeing bad information.)

Documentation changes

Contributor guides will need to clarify the purposes of main and development on documentation. This includes code contributors, as they are meant to be the primary submitters to development.
Signposting on dev.o3de.org indicating that the user is on the "development branch site" documenting the current code base, in the form of a site banner or other visible UI.
Signposting on specific o3de.org landing pages pointing users to the development site.

Technical considerations

Outlined above regarding implementation.

Are there any alternatives to this feature?

Full rollout of a versioned website, date TBD.
Separating development and 2111.2 into separate subdirectories on the site, but with no easy UX to navigate between them.

Are there any open questions?

Is dev.o3de.org an appropriate name?
Should we wait for full versioning?
Is this model going to be easy to migrate to a versioning system?
Should robots be prevented from indexing dev.o3de.org?
Which pages on o3de.org should have signposting for how to get to the development branch documentation?

Proposed SIG-Docs-Community meeting agenda for 2021-06-16

Meeting Details

Date/Time: June 16th, 2021 @ 9:00pm UTC / 2:00pm PT
Location: Discord server #sig-docs-community voice channel.
Moderator: Stephen Tramer (@sptramer)
Note Taker: TBD

The SIG Documentation & Community Meetings repo contains the history past calls, including a link to the agenda, recording, notes, and resources.

Proposed Agenda

Agenda items have an allotted time which presenters are expected to stick to. If items finish discussion earlier than their allotted time the meeting will roll into extended Q&A. Additional agenda items will not be picked up during the meeting, so that presenters may be given time to prepare.

Amazon update - Amazon docs team - 10min: Update on the roadmap, priorities, progress, and site status for launch.
Formal charter review - Stephen Tramer (@sptramer) - 20min: Formal evaluation of the D&C SIG charter and discussion, especially to identify areas of concern or areas where we lack coverage.
Please read the charter in preparation. Additional charter discussion will happen in the SIG repo issues following the meeting.

Time remaining for proposed agenda items: 30 minutes

Meeting agenda will be finalized on 6/15. Please vote before 8AM PT.

Items marked with a 🎉 reaction have been accepted onto the agenda.

Proposing items

Community members who wish to propose agenda items or vote on them can do so here. For pre-release meetings, proposed items which get the highest votes will be used to fill available time. Remaining items can be re-proposed on the next meeting agenda, or taken up as ad-hoc discussions among the SIG.

To propose an agenda item: Leave a comment on this issue with the following information:

Topic
Presenter
Length of time (10m max)
Description

After leaving your comment, add 👍 and 👎 reactions so that the community can vote.

To vote on agenda items: Use the 👍 and 👎 reactions to upvote/downvote proposed topics in the comments.

o3de / sig-docs-community Goto Github PK

sig-docs-community's Introduction

O3DE Documentation & Community Special Interest Group

D&C SIG Responsibilities

How can you contribute?

FAQ

Meeting Agenda

Contact

Documentation release process

sig-docs-community's People

Contributors

Stargazers

Watchers

Forkers

sig-docs-community's Issues

The chair / co-chair roles

Responsibilities

Nominations and election

Nomination requirements

How to nominate

Election process

Meeting Details

SIG Updates

Open action items

Newly resolved items

Initial Agenda

Suggesting and voting on agenda items

Agenda item format

Meeting Details

SIG Updates

Open action items

Newly resolved items

Initial Agenda

Suggesting and voting on agenda items

Agenda item format

Meeting Details

SIG Updates

Initial Agenda

Suggesting and voting on agenda items

Agenda item format

Meeting Details

SIG Updates

Open action items

Newly resolved items

Initial Agenda

Suggesting and voting on agenda items

Agenda item format

Sig-Docs-Community

Onboarding

Experience design

Actor development

World building

Look development

Multiplayer

Project development and team collaboration

Editor extension

Packaging and deployment

Nomination Guidelines

Documentation reviewer

Meeting Details

SIG Updates

Open action items

Initial Agenda

Suggesting and voting on agenda items

Agenda item format

Documentation maintainer

Reviewer/Maintainer Nomination

Fill out the template below including nominee GitHub user name, desired role and personal GitHub profile

Meeting Details

SIG Updates

Open action items

Newly resolved items

Initial Agenda

Suggesting and voting on agenda items

Agenda item format

Summary

What is the motivation for this suggestion?

Suggestion design description

What are the advantages of the suggestion?

What are the disadvantages of the suggestion?