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

[sptramer]

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: https://github.com/o3de/sig-docs-community/issues/38#issuecomment-1096978140) (@sptramer to raise to TSC and LF)

Open RFCs

• [x] https://github.com/o3de/sig-release/issues/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!

:+1: reactions to proposed agenda items are counted as YEA votes for taking up discussion, and :-1: 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 :+1: and :-1: reactions manually, so they appear and are obvious to voters!

[sptramer]

Holdover item (https://github.com/o3de/sig-docs-community/issues/35#issuecomment-1055825739) - Initially filed by @chanmosq, voted 3 :+1: / 0 :-1:

Topic: Cultivating a friendly writing style and tone in O3DE Docs Presenter: @AMZN-Gene @chanmosq Length of time: 15 minutes to explain situation come up with next steps. If time allows, maybe more discussion.

O3DE Documentation tend to have a more technical and matter-of-fact tone. While this is appropriate for writing docs, tutorials have a more casual nature and can benefit from a friendlier tone. A friendlier tone can make documents more welcoming and easier to understand.

We want to address the expectations/standards for docs reviewers and contributors regarding cultivating a friendly tone where it's appropriate.

[sptramer]

Holdover item (https://github.com/o3de/sig-docs-community/issues/35#issuecomment-1068205965) - Initially filed by @sptramer, voted 1 :+1: / 0 :-1:

Topic: SIG role in tooltips, in-editor help, etc etc Presenter: @sptramer Length of time: 10-15m

The docs sig occasionally gets requests to review in-editor help information, and most importantly, our role in in-editor help has come up across the PRs https://github.com/o3de/o3de.org/pull/1339 and https://github.com/o3de/o3de/pull/6555. Engineers may be unwarily making changes which impact the user experience of documentation, and we should consider the sig-docs-community role in making sure that in-Editor documentation resources (whether static strings, site links, or something else) are appropriately reviewed and updated.

[aFinchy]

Topic: News feed presented in editor when starting the engine Presenter: Amy (Finchy) Length of time: 5 Minutes.

When starting the editor there would be a feed on engine news (For example versions, or could be blogs). This would help get traction to the site as well as help show people up-to-date news who may not follow the updates and stays developing in the engine.

A example of this is when you start the Lumberyard Engine and you see the news feed in editor. The engine also shows current news when loading the engine.

[AMZN-Gene]

A example of this is when you start the Lumberyard Engine and you see the news feed in editor. The engine also shows current news when loading the engine.

How cool would it be if the news popup had a timer showing the last development branch update. Like "O3DE engine was was last updated 1 hour ago" and it could hyperlink to the dev branch on GitHub.

[chanmosq]

Meeting notes on Writing Style/Tone Guide Initiative:

• The motivation behind this initiative is to allow different writing styles and tones in the O3DE documentation. Currently, most of the existing docs embody a technical tone, set forth by writers and editors who wrote feature documentations and references during the early stages of O3DE Docs. Moving forward, we want to expand the accepted writing style and tone to include casual, more friendlier tones.
• The original proposed solution was to create recommended guidelines for writing in both technical and friendly tones. It would address topics such as: deciding which tone is appropriate for which type of document and writing examples for both.
• A major concern regarding the original proposed solution is that more rules will discourage contributions and add strain to editors and reviewers.
• Alternative approach is instead of making more rules, we loosen the currently enforced rules. Generally, a technical tone has more requirements than a friendly tone, and our current O3DE Writing Guide already caters to a technical tone. What we can do instead is differentiate which tones are appropriate for which docs, specify all-around writing requirements, and further specify writing requirements for technical docs. This leaves other docs free to be written in a technical, friendly, or in-between tone.
• Our goal remains to create guidance on writing style and tone for O3DE documentation.

[ghost]

Meeting notes on Writing Style/Tone Guide Initiative:

• The motivation behind this initiative is to allow different writing styles and tones in the O3DE documentation. Currently, most of the existing docs embody a technical tone, set forth by writers and editors who wrote feature documentations and references during the early stages of O3DE Docs. Moving forward, we want to expand the accepted writing style and tone to include casual, more friendlier tones.
• The original proposed solution was to create recommended guidelines for writing in both technical and friendly tones. It would address topics such as: deciding which tone is appropriate for which type of document and writing examples for both.
• A major concern regarding the original proposed solution is that more rules will discourage contributions and add strain to editors and reviewers.
• Alternative approach is instead of making more rules, we loosen the currently enforced rules. Generally, a technical tone has more requirements than a friendly tone, and our current O3DE Writing Guide already caters to a technical tone. What we can do instead is differentiate which tones are appropriate for which docs, specify all-around writing requirements, and further specify writing requirements for technical docs. This leaves other docs free to be written in a technical, friendly, or in-between tone.
• Our goal remains to create guidance on writing style and tone for O3DE documentation.

Great suggestions! Thank you

[FiniteStateGit]

No meeting notes produced.