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

[FiniteStateGit]

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). Proposed SIG-Docs-Community Feature Grid #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!

[ghost]

Hi,

It would also be great to keep the Discord moderators up to date so that we can give directions to people with these questions. Everythings gets lost today in the sea of messages thrown around at various channels.

We should get better to direct people into a Q&A forum. As much as I like chats to resolve occasional installation issues for persons X, Y and Z; they tend to be hard to search and find old information, unless you end up lucky asking the question in the same time zone a person is around to answer it.

Lumberyard used to have a forum where people could search and find things. I proposed in the past to open up a Stack Overflow for Teams where it can connect to Github as well as posting knowledge base stuff, Q&As, and all other kinds of functions that come along in that platform.

https://stackoverflow.co/teams/pricing
https://www.youtube.com/watch?v=MQxlE0ICumI

Sincerely,
Niklas

[willihay]

tl;dr: o3de.org needs clarification on what samples and tutorials can be included in the "learning-guide" part of the website: https://www.o3de.org/docs/learning-guide/.

The Contributor Guide topic on the website's docs structure is very specific about samples:

"The Samples section contains documentation for samples that are included with the O3DE distribution."

However, this raises the question why is the Kythera sample listed, since it is not included in the o3de repo? (It's available for download separately from a Kythera website.) Does the wording in the Contributor Guide need to be clarified?

The description for tutorials only talks about their assets, and not what tutorials are permitted:

"Tutorials should only use assets that are part of the O3DE distribution, are freely available, or can be quickly and easily replicated in open source content creation tools."

Perhaps what we need is an approval process whereby samples and tutorials can be approved to appear on the docs site.

We should also be clear about how much documentation can appear on o3de.org.

For samples, do we allow detailed and complete usage documentation on the site? Or do we limit content to something along the lines of a screenshot, a paragraph overview, and a link to the full set of usage docs that is expected to be hosted elsewhere?

For tutorials, what is permitted? Do we restrict tutorials to Gems that are included with o3de source? Or do we permit tutorials for remote projects and Gems if they've gone through an approval process?

A similar question applies to reference documentation for Gems that are not included in the o3de repo, although that might have additional concerns and a different timeline, and therefore require a separate discussion.

Decisions should be documented in the Contributor Guide.