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 #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?
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?
What are the disadvantages of the feature?
Feature design description
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:
Are there any alternatives to this feature?
Are there any open questions?