search

18F / uswds-jekyll

A Jekyll theme showcasing the U.S. Web Design System
https://federalist-proxy.app.cloud.gov/site/18f/uswds-jekyll/
Other
135 stars 121 forks source link

proposal: make more opinionated #190

Closed afeld closed 3 years ago

afeld commented 4 years ago

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 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:

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:

Thoughts?

cc @thisisdano

cmajel commented 4 years ago

👋 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:

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.

davemcorwin commented 4 years ago

Thanks @cmajel !

  1. We've had some internal discussions about the differences between the two, but at a high level, uswds-jekyll is 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.

  2. Federalist is agnostic, any Jekyll, Hugo or Node site generator (or plain ol static file) works 💯 on the platform.

  3. 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.

afeld commented 4 years ago

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?

afeld commented 4 years ago

Deck about the 18F template from @cmajel

afeld commented 4 years ago

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. https://github.com/18F/tts-tech-portfolio/issues/419

afeld commented 4 years ago

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.

adborden commented 4 years ago

I am a big :-1: 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).

thisisdano commented 4 years ago

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.

Related: https://github.com/18F/tts-tech-portfolio/issues/419#issuecomment-607451905

adborden commented 4 years ago

+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 %}
its-a-lisa-at-work commented 4 years ago

@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?

afeld commented 4 years ago

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.

afeld commented 4 years ago

We can make another issue that points to it, if that helps.

its-a-lisa-at-work commented 4 years ago

If we're going to be doing it, than I'd say yes; otherwise, let's move it to the column where we watch other items.

On Mon, Jul 13, 2020 at 7:32 PM Aidan Feldman notifications@github.com wrote:

We can make another issue that points to it, if that helps.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/18F/uswds-jekyll/issues/190#issuecomment-657875414, or unsubscribe https://github.com/notifications/unsubscribe-auth/AHPQBHWZO5GO5HXFSMNXXFLR3OKQRANCNFSM4LVIEZBA .

-- Alyssa Feola Cybersecurity Advisor Technology Portfolio GSA | FAS | TTS | QQ3 alyssa.feola@gsa.gov cell: 202-322-8267

afeld commented 3 years ago

This project is in maintenance mode, so closing.