proposal: make more opinionated
afeld opened this issue · comments
Had a discussion with @davemcorwin and @ryanhofdotgov today where we were discussing uswds-jekyll, its use, and its relationship to federalist-uswds-jekyll. We identified some distinctions that weren't clear to me before:
- uswds-jekyll is a "theme"
- Gets pulled in to sites as a dependency
- Best suited for documentation sites that don't want to think about anything other than the content
- federalist-uswds-jekyll is a "starter"
- Gives boilerplate that is meant to be customized
- Not meant to be a dependency in the NPM package / Ruby Gem sense
- Once you start off creating your own site with it, you're on your own
- Best suited for sites that are meant to have a distinctive/customized layout/look
uswds-jekyll could do better at the "don't want to think about anything other than the content" part. We can take out a lot of the customization options and thus make it much easier to adopt, upgrade, and maintain. My thought is that we should design it to cover the majority of TTS microsites, make it just customizable enough to be usable by other organizations, but not try to be everything to everyone. Examples:
- Remove the page subnavigation configuration and have it generated automatically for all the headings, a la the Handbook
- Get rid of the hero, tagline, and graphics list—folks can put in custom HTML if they really want something like that
In other words, let's bring uswds-jekyll back around to be closer to its predecessor, the 18F Guides Template.
Example sites uswds-jekyll is or should be used on:
- Handbook
- Engineering Practices Guide
- Before You Ship
- Product Guide
- Accessibility Guide
- Methods, arguably
Thoughts?
cc @thisisdano
👋 A heads up that @brentryanjohnson and I have also been working on a "don't want to think about anything other than the content" template for guides that have USWDS and 18F styles baked in. We saw that the guides template was antiquated, and teams, who often don't have dev resources or skills, still needed help to customize templates and integrate 18F styles / branding elements.
We've been working from the federalist-uswds-jekyll templates since we've seen many teams and projects start from these templates, and generally use federalist for hosting / previewing. A (still very in-progress) fork is here:
https://github.com/cmajel/federalist-uswds-jekyll
We've focused mostly on theming, but things like an auto generated sidnav are great enhancements (@brentryanjohnson experimented with this in his new version of the 18F content guide).
Some questions I have about uswds-jekyll vs federalist-uswds-jekyll:
- would
uswds-jekyllallow us to customize the styles in the same way asfederalist-uswds-jekyll? - My understanding is the Netlify CMS is part of federalist, but maybe not part of
uswds-jekyll- is that right? This could be a helpful feature for non-dev authors who are maintaining guide sites in the future.
It feels like there's a lot of overlap, so we wanted to share what we have done so far as this conversation gets started.
Thanks @cmajel !
-
We've had some internal discussions about the differences between the two, but at a high level,
uswds-jekyllis less-easily customizable, but much more configurable so it may be better suited to cases where there are not a lot of developer resources available. At the end of that day, it is your app and each can be customized as much as you want. -
Federalist is agnostic, any Jekyll, Hugo or Node site generator (or plain ol static file) works 💯 on the platform.
-
Netlify CMS is its own thing and can be added to any site that wants to use Github as a content store. Federalist merely acts as an authentication middleman with Github so the site owner does not have to roll their own or use Netlify itself.
working on a "don't want to think about anything other than the content" template for guides that have USWDS and 18F styles baked in.
Let's please, please not ship yet another theme without deprecating another. Let's see if we can combine efforts here.
his new version of the 18F content guide
Can we do that in a branch of the existing content guide repository so we don't have as much repository sprawl?
I'm going to write something more extensive/holistic to explain my reasoning for saying what I did above. Will get to y'all Tuesday latest. GSA-TTS/tts-tech-operations#419
To elaborate on the initial proposal, the thinking here would be to aim for the TTS sites above as the primary use case, while making the theme just flexible enough to be usable by other organizations. This might mean allowing overriding the logo and maybe changing the banner/footer color, but not much more than that.
I am a big 👎 on uswds-jekyll as it exists today. While the intentions were good to create a customizable thing that you didn't need a developer for, instead it created its own domain specific language in the form of YAML and without sufficient docs or tests and no easy way to upgrade USWDS or pull in security fixes. I think we would be better off supporting minimal customization as @afeld is hinting at while allowing folks to refer to Jekyll docs on how to override and customize if they choose.
I had written up some recommendations on starter templates + themes for Federalist in 2018, but some bits of that write-up might be relevant to this discussion. The goals for these recommendations were about making Federalist more approachable to low-tech users (exactly what @cmajel is after), and allowing a straightforward upgrade path with USWDS (update your theme gem to update USWDS) while allowing an escape hatch for advanced uses (think create-react-app eject).
Thanks for sharing that document @adborden — I'm sorry I either never looked at it before or completely forgot it existed. I'm very much on board with the Provide a minimal USWDS Jekyll theme, and I think that's consistent with a lot of our goals here. It's what I think I would choose to do with uswds-jekyll. The only other thing I think I might want to include in that Jekyll theme would be templated includes for simple USWDS components so a project might be able to do something like {% include uswds/usa-button text="Submit" %} if they desired.
+1 for some simple includes.
Don't want to get too crazy to start, but you could also create a Jekyll plugin to define new liquid tags that would handle more complex USWDS components. I'm just pointing this out to say Jekyll provides several tools for us to use, yaml configuration, includes, plugins, etc. and we should choose the right tool for the job, instead of going all-in on one (like uswds-jekyll feels like all-in on YAML).
For example, using templates, this starts to feel a little clunky and might be better implemented as a block tag.
{% capture content %}
If you’re unfamiliar with [GitHub](https://github.com), the Federalist team
recommends that you <em>familiarize</em> yourself before continuing
through this guide.
{% endcapture %}
{% include components/alert--note.html content=content %}
@afeld is this something that we're doing or that we're watching? If we're doing, could we move over to the TTS Tech Portfolio repo for better issue tracking?
is this something that we're doing or that we're watching?
Could go either way.
If we're doing, could we move over to the TTS Tech Portfolio repo for better issue tracking?
Would prefer to keep it here, for discoverability by those who visit this repo.
We can make another issue that points to it, if that helps.
This project is in maintenance mode, so closing.