Proposed SIG-Docs-Community Feature Grid about sig-docs-community

[willihay]

Assuming this is a companion or addition to the product feature grid in the upcoming 22.05 release notes?

How did you determine the completeness score for the conceptual and tutorial content? What does "Complete" mean for docs? I think we should wait to release this until the Amazon docs team has had a chance to provide input from its audit, which is currently ongoing. I have a feeling there will be a lot less "Complete" scores than currently shown here. ;-)

We should only list modules that are included with O3DE. Kythera AI is not one of them.

Regarding the general format, please put the score first, followed by the description. Sorry for the extra work this will cause, but this will allow the scores to line up neatly and really aid the ability for readers to rapidly scan the table. See the preview of the product feature grid as an example, sizing your window to fit the table contents.

[FiniteStateGit]

Assuming this is a companion or addition to the product feature grid in the upcoming 22.05 release notes?

Yes, this is the feature grid for documentation. Stephan and I settled on the workflows, modules, and columns to include last week. I think we both agreed that the format should be improved for future versions; I had concerns that this had to largely align with the format of other feature grids.

How did you determine the completeness score for the conceptual and tutorial content? What does "Complete" mean for docs? I think we should wait to release this until the Amazon docs team has had a chance to provide input from its audit, which is currently ongoing. I have a feeling there will be a lot less "Complete" scores than currently shown here. ;-)

For conceptual content, if I couldn't identify that material was missing from the topic, it received a 'complete' score. For tutorial content, I considered all procedural material in addition to topics in the Tutorial section. I was expecting/hoping for many corrections to individual scores, I know the current ones are overly optimistic.

I will remove Kythera. I can shuffle the score and description around no problem (and change which descriptions we use), generating the feature grid is automated!

[sptramer]

Notes from 5/17 meeting:

• Maybe change from a separate feature grid to just a 4-col extension on top of the existing O3DE feature grid?
• "Conceptual content": Feature descriptions (Minimum viable content), and cross-component/larger-engine tie-together
• Which is more useful:
  • Classifying by workflow feels problematic; Might be useful for prioritization and understanding of product health but not appropriate for feature grid
  • Developers look at specific feature support like "Animation motion matching" - not just the overall state of "Animation"
  • Not every feature needs every type of documentation (i.e. Installer doesn't need component docs, and viewport interaction doesn't necessary need "samples")
  • Lots of SIGs are not accurately tracking their own content needs on the feature grid, with regards to either 3D assets or sample code/projects (we help with the latter, TBD SIG helps with the former)
• How do we score, and when can we give a score of "Complete" to any feature row?
  • Maybe grade on the content quality bar? i.e. "None", "Minimum", "Partial", "Good", "Excellent" gradation? This avoids the unpleasant implications of "complete" as well
  • But "Complete" does make sense for things like reference documentation: Lua, Script Canvas, Components, API ref, etc.
• How do we track platform-specific support?
  • Release, install, platform-specific capabilities
  • Platform-related best practices for areas such as assets, networking design, etc.
• Should other SIG-docs items have a place on the feature grid? Outside of reporting docs on product, what else does the SIG need to report on?
  • i.e. Projects, initiatives, ongoing RFC acceptance, templating, contributing
  • Some of this is reporting to be handled through LFX dashboard (metrics)
  • Publishing and health of standards and practices (such as contributor guide, audience calibration, style guide, levels of content, etc.)
  • Core gem coverage - possible additional area of RYG, for overall health of a single Gem, rather than by featureset.
• Engineers want to use the term "included gems" or "bundled gems" - this helps distinguish from the engine core, and also the "core set of gems" required for every project
  • Feels like also a TSC/Marketing terminology thing?
  • Users should be able to make trust decisions on their own without an explicit "blue check" endorsement from O3DE or the O3DF - this is also a differentiator between "included" (more trusted)/"external" (trust if you want)
  • Avoid the "third party" terminology in general (feature grid and otherwise)
• Enumerate the type of tutorial content available: Written, interactive, cookbook/recipe, sample code, sample project, howto
  • Could explode into "sub-grids" on top of each content type category - how do we avoid adding dimensions to the feature matrix and track appropriately without an information overload?
    • Maybe this is a feature request to the sig grid tool, where we enter EXTRA information that can be used to generate 2 charts: A SIG-relevant chart (detailed breakdowns) and a user-relevant chart (single category score - priority)
      • Are the detailed breakdowns just covered by rigorous github issue use and appropriate labeling?

[sptramer]

Important downstream consequences of accepting this change:

• We'll need to update the source code for the feature grid to accept docs information.
• We'll need to update the instructions on how to use the feature grid.
• Should be future-proofed in terms of API reference generation so that we can link to red/yellow/green status dashboards for coverage.

[tonybalandiuk]

I think this information is useful in a table form, but

1. it will require maintenance
2. this information seems like it would be very useful at the top of each documentation page so someone using the actual documentation the completeness of it immediately (as opposed to having to know that this table exists).

I'm wondering if there's a way to have this information at the top of each docs page, and then somehow run a script to aggregate it into this table. Then both use cases would be fulfilled.

[FiniteStateGit]

Closing proposal, feedback has been incorporated into RFC #64.