Added placeholder pages for all missing components

[jjjoness]

Signed-off-by: John Jones-Steele 82226755+jjjoness@users.noreply.github.com

Change summary

There are a number of components in the engine that either did not have a "?" button or that button pointed to a non-existent or wrong page. o3de/o3de#2321. This is being addressed with o3de/o3de#6555 and part of the task is to create the missing pages as placeholders.

Submission Checklist:

[chanmosq]

@jjjoness Can you resolve the merge conflicts? It seems like some of the missing pages that you created placeholder pages for are now up on the website, so you no longer need to create a placeholder for them. Also, I noticed there are some .md.bak files committed -- can you remove those?

[FiniteStateGit]

#1351 is still in the works, which adds the gradient component references.

[jjjoness]

@chanmosq Merged from main and fixed conflicts.

[micronAMZN]

The docs team has been discussing how to handle this issue because we can't merge empty placeholder pages into docs.

For new topics we minimally need:

• Complete frontmatter. In this scenario linktitle, title, and description.
• A couple of sentences in the body of the topic that introduce the feature.

The other issue is exposing pages that have been set to draft. The Blast docs, for example, are currently hidden because there is no viable way for users to create a Blast asset required to use the components. Once this issue is solved, the Blast docs (not just the component pages) need to be updated for the new process of creating Blast assets. We hid these docs because users were wasting a lot of their time trying to figure out how to use Blast without knowing it currently isn't a functional feature.

Adding @yuyihsu for this suggestion.

Can we implement a disabled/hidden state for the help button in the UI for scenarios where non-working features can't be removed/hidden from distribution, or scenarios where useful documentation cannot be provided? We understand the help button has to link to something, but linking to empty topics or misleading information is not a good user experience.

[sptramer]

Officially seconding @micronAMZN's comment. While this addresses the issue (links go to 404) it does not resolve the actual core problem or provide future-proofing. The idea to make a UI/UX improvement where it becomes visible when help files are not available in the editor due to the lack of a HelpPageUrl attribute addresses both of those issues; it prevents users from reaching a 404 due to unpublished content, and future-proofs. This will also allow developers to prototype and bring online code before there are official docs, which will be a frequent occurrence for high-velocity or in-development features, especially as the website becomes versioned around releases and does not keep pace with development.

[tjmichaels]

Officially seconding @micronAMZN's comment. While this addresses the issue (links go to 404) it does not resolve the actual core problem or provide future-proofing. The idea to make a UI/UX improvement where it becomes visible when help files are not available in the editor due to the lack of a HelpPageUrl attribute addresses both of those issues; it prevents users from reaching a 404 due to unpublished content, and future-proofs. This will also allow developers to prototype and bring online code before there are official docs, which will be a frequent occurrence for high-velocity or in-development features, especially as the website becomes versioned around releases and does not keep pace with development.

FYI, this is already how the code should work. If a HelpPageUrl isn't defined, it should not show the ? button. The 404 issue should only happen when a URL is added that points to an invalid web page. The question then becomes what's the best experience for the customer:

• That some components have a ? button and some do not
• That the ? displays and takes you to a generic page (like components)
• That the ? displays and takes you to a mostly empty page with minimal useful data

@yuyihsu can you please weigh in here and then @jjjoness can make the appropriate thing happen. Thanks!

[AMZN-alexpete]

The docs team has been discussing how to handle this issue because we can't merge empty placeholder pages into docs.

For new topics we minimally need:

• Complete frontmatter. In this scenario linktitle, title, and description.
• A couple of sentences in the body of the topic that introduce the feature.

I think the goal was for these placeholder pages to not be empty, but to match the same minimum-bar demonstrated by many of our existing reference pages eg.
https://www.o3de.org/docs/user-guide/components/reference/atom/bloom/
https://www.o3de.org/docs/user-guide/components/reference/atom/deferred-fog/
https://www.o3de.org/docs/user-guide/components/reference/atom/directional-light/
https://www.o3de.org/docs/user-guide/components/reference/atom/display-mapper/
https://www.o3de.org/docs/user-guide/components/reference/atom/entity-reference/
https://www.o3de.org/docs/user-guide/components/reference/atom/exposure-control/
https://www.o3de.org/docs/user-guide/components/reference/atom/global-skylight-ibl/
etc.

[tjmichaels]

The docs team has been discussing how to handle this issue because we can't merge empty placeholder pages into docs.
For new topics we minimally need:

• Complete frontmatter. In this scenario linktitle, title, and description.
• A couple of sentences in the body of the topic that introduce the feature.

I think the goal was for these placeholder pages to not be empty, but to match the same minimum-bar demonstrated by many of our existing reference pages eg. https://www.o3de.org/docs/user-guide/components/reference/atom/bloom/

Completely understood. I would just like a UX call on what is actually the best experience for the customer. Happy to do that, but this is the 2nd iteration (each targeted a different solution and received pushback or disagreement) and I just want to have a clear decision made and agreed upon so that we can move in the right direction.

[amzn-leenguy]

The docs team has been discussing how to handle this issue because we can't merge empty placeholder pages into docs.
For new topics we minimally need:

• Complete frontmatter. In this scenario linktitle, title, and description.
• A couple of sentences in the body of the topic that introduce the feature.

I think the goal was for these placeholder pages to not be empty, but to match the same minimum-bar demonstrated by many of our existing reference pages eg. https://www.o3de.org/docs/user-guide/components/reference/atom/bloom/

Completely understood. I would just like a UX call on what is actually the best experience for the customer. Happy to do that, but this is the 2nd iteration (each targeted a different solution and received pushback or disagreement) and I just want to have a clear decision made and agreed upon so that we can move in the right direction.

I am not the poc UX reference here (it seems like @yuyihsu is), but if I was to make a call here, I would say I am fine with this direction for now. Although I'd like at least a little more text information and at least an image of those pages like I can see here: https://www.o3de.org/docs/user-guide/components/reference/atom/diffuse-gi/

If this is asking too much, I understand.

I also think the line "To do: Add properties." is really vague. Could we update this to something a little more human?

Like: "To do: Want to help update this page? Join the O3DE community on GitHub, and help us update this page from this list." Or something similar..

[chanmosq]

Of the options that @tjmichaels suggested, I think these two seem the most helpful to customers. We can select an option case-by-case.

(Option 1) That some components have a ? button and some do not
(Option 3) That the ? displays and takes you to a mostly empty page with minimal useful data

For option 3, @AMZN-alexpete listed some good examples of minimal component docs, such as this one. To echo @amzn-leenguy and @sptramer, a minimal component doc should contain:

• Accurate metadata (as @jjjoness provided in the pages created).
• A 1-2 sentence description of what the component is.
• (Strongly encourage) Creating an issue in o3de.org to complete this component doc, and in the component docs, adding a "To do" shortcode that links to that issue and briefly describing what's needed.

Option 1 is good solution for components in which the minimum documentation can't be reached. For example, we can't produce proper documentation for the Blast component docs that @micronAMZN mentioned. In this case, I think having a [?] button that leads to empty docs or inaccurate info won't be helpful to the user.

[jjjoness]

No longer needed as per #6555 .