Proposed SIG-Docs meeting agenda for 2022-04-26 about sig-docs-community

[sptramer]

Holdover item (#35 (comment)) - Initially filed by @chanmosq, voted 3 👍 / 0 👎

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 (#35 (comment)) - Initially filed by @sptramer, voted 1 👍 / 0 👎

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 o3de/o3de.org#1339 and o3de/o3de#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.

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.