[SITE][FEATURE] Revise website's information architecture to improve user experience

[chanmosq]

Describe the feature you'd like available on the website

Based on user studies where the user must find a documentation on the website, the following friction points were found:

• To find tutorials, users look to the corresponding section in the User Guide, not the Learning Guide.
• Users expect to find information on programming in a high-level Programming Guide. The User Guide is their last choice.
• When asked to "Extend the Editor", users first choice is the Tools UI, because of the keyword "tools". However the Tools UI only covers the front-end. What they are really looking for is the Programming Guide, which again is hidden in the User Guide.

Proposed implementation

Further discussion is required.

Available alternatives

Supplements

[micronAMZN]

Further information for UI/UX:

The docs are still a work in progress. We've not had the time to fully develop the current architecture and I don't think we should revise the architecture based on feedback for an incomplete implementation without much consideration.

1. We have very few tutorials and many feature sections have stale or incomplete documentation. The goal is to provide a central location for tutorials for users who'd like to learn by working through hands on examples. The central location also makes the tutorial content, which is very volatile, easier to manage and maintain. The tutorials are to be linked from the corresponding feature documentation, which will solve the issue of discoverability of tutorials.
2. Originally there was a separate Programming Guide, but after some consideration and analysis of documentation sets for similar projects and commercial engines, it was decided that it made sense to include it in the User Guide. We can do a better job with our top level landing pages to improve discoverability. In practice, it's often difficult to figure out where the line is drawn between what should be in a User Guide vs a Programming Guide when it comes to game development.
3. We really struggled with the name of the Tools UI section because we need to differentiate between developing UI for a project and developing a UI for O3DE Tools. My suggestion is for a single UI section in the User Guide split into Project UI topics and Tools UI topics. The branding section should be moved to a higher level somewhere else on the site, and out of documentation.

[yuyihsu]

Adding contexts from WTE research:

During the WTE research for WF8, several users had issues finding the help content they need to extend the engine. In the task when asked to build a python gem, some users browsed the site and spent a long time in the "User Guide" looking for help. They went to "Gems", "Project Manager", "Build", and finally "Gem Development" under Programming to look for the info, some users also went to the "Tools UI Developer’s Guide" and API references and failed to find the info they needed. None of them went to the Tutorial section in the first place, even through Search.

Considering that in the current IA design on the Docs site, the contents for engine users and engine developers are mixed together, and the help contents for engine users occupied 80% of the site contents. This makes it hard for the Engine Developers to identify the info they need, and they are required to spend extra cognitive load to read through the titles to make sure they didn't miss any important info.

Users also mentioned that they'd prefer to have a separate section that only contains the help content for engine development, and don't mix these contents with the engine user guide.

For those users who started from search, they also had a hard time finding their way to the tutorials section. The results for engine development and user guide are mixed, and actual link was listed down in the search result list.

[ShaunaGordon]

Resurfacing this for longer-term clean-up, since this has come up again in Discord recently. Here are some of my own thoughts:

Docs Landing Page

The main docs page has the right idea, I think, in that it groups things by the kind of role that the user is doing -- engine development, engine user, etc. However, I don't think it's consistent (tutorials, API docs, and contribution guide are in there, too), which adds to the confusion.

I wonder if we lay that out based more on the person's role, and drop them onto a page that lists the resources that kind of person needs?

So maybe the blocks look more like this:

• I want to work on the engine (Engine Developer)
  • Inside, it would have the Engine Developer's Guide, the API Reference, and the Design System reference (and maybe the Atom Renderer reference?)
• I want to work with the engine (Game Developer/Engine User)
  • Inside, it would have the User Guide, the Atom Renderer Reference, and Tutorials
• I want to write a Gem/Component for the engine (Gem Developer)
  • Inside, it would have the Gem Developer Guide (this one's kind of a new one, from what's buried in the main guides currently), the Gem Reference, the API Reference, and the Design System Reference

The internal links could even be lists in the blocks themselves, so there aren't extra clicks.

The tree menu within each section can also be improved by listing the other sections. Even if they're just links and not tree branches, it would help with navigation once the user is inside a section.

Search

Search can be improved in a few ways:

1. Add autocomplete/suggestions to the search box with the 3-5 most relevant results. Down+Enter allows the user to go to one of the suggestions, bypassing the search results page, or simply hit Enter to go to the search results page.
2. On the search results page, add to the header links the section/guide in which that item is located. So instead of Editor Python Bindings Gem, it might be Gem Reference: Editor Python Bindings Gem or Editor Python Bindings Gem | Gem Reference. Alternatively, results could be grouped (and eventually filtered) by section.
3. Add a directive to boost certain sections in the search results if the query has certain words. For example, including the word "gem" would boost results in the Gem Reference and Gem Developer sections.
4. Review the search engine, itself, and see if there's a better solution these days.

Overall Design

This one's more of a question, but how married are we to the design of the docs site? There are a few other Hugo template options out there. It's possible one of them might suit it better these days.

Taxonomy

Hugo has a pretty powerful taxonomy system. I wonder if we could leverage it to help link more pages together?

In a blog setup, it typically defaults to tags and categories, but I've added series to my own, and it's pretty arbitrary what taxonomy terms are added and where they're used. We could add taxonomy to pages and then add "similar pages" to the bottom of articles that key off that taxonomy. So tutorial pages would suggest other tutorials with the same tags, or would link to related API other reference pages.