Proposed RFC: Feature Site Structrual Revamp

[ShaunaGordon]

Feature Site Structural Overhauls

I noticed that the site is currently using a home-rolled template. This is...okay...but it does mean that we miss out on a lot of the more robust features and whatnot that using and customizing an off the shelf docs template would give us. For example, we have to make our own dark theme, or internationalization. Additionally, the original team put the main site content into the layouts, thus mixing content and template/structure. This makes it really hard for contributors to know where to look, and with all the Boostrap stuff, it's really hard for even seasoned engineers to sift through the content for the non-docs portions of the site.

What is the relevance of this feature?

This is important on an end-user usability front (tried and tested designs), a maintenance front (separation of concerns, balancing build vs "buy"), and a contribution front (content structure is more predictable and content contributors don't have to wade through code/markup).

What are the advantages of the feature?

• Easier for content contributors to actually contribute
• Features already available, such as internationalization, dark mode, robust search, etc
• Easier maintenance overall (hard separation of structure and content also allows themes to be more easily swapped out or modified)
• Separating the theme out into its own repo might make it less daunting for content-only contributors
• This will close a lot of bug/feature tickets around the structure and operation of the site itself, and will make Roadmap: First draft o3de.org website information architecture for usability testing #101 easier to solve and implement

What are the disadvantages of the feature?

• The conversion will be a pretty big lift and may take a fair bit of time if done in phases.
• A lot of content needs to be teased out from structure.
• Architecture decisions need to be made about how best to organize the content to play nice with the template, even if we stick with the homegrown one.

Feature design description

• Explain the design of the feature with enough detail that it could be implemented.

Technical considerations

This shouldn't affect external repos or tools. Hugo will still work and build things the way the external tools expect.

Scope of work

Steps to do this:

• Extract content from templates and put them in markdown files in the content folder
  • Decide how to structure the non-docs and non-blog page content so it lays out as expected with the existing design
• Templatize the layouts to properly consume the content
  • This can be done in a bit of rough-and-ready way if we decide to use an off-the-shelf template (by hard-coding the files a given fragment reads and outputs)
  • If we decide to just make what we have a template, extract the template into its own repo so that it works the same way as off-the-shelf templates, and so that we can separate content updates from structural ones
• If switching templates, convert to the new template (this takes a little setup to change parameters and whatnot for the features we want to use)
  • Make any customizations that we want to make to individual pages to maintain the desired look and feel

Are there any alternatives to this feature?

• Maintain status quo. Don't overhaul it, leave it as is.
• Only extract content from templates and keep template in the site repo.
• Start over from scratch and migrate the content over. (This just seems like a bad idea.)

Are there any open questions?

• What are some of the open questions and potential scenarios that should be considered?