[WIP][Experiment] Make the guide as a tool for decision-making, rather than a set of opinions #213

hbillings · 2019-07-19T22:52:36Z

After some discussions about how things get documented and maintained (or not) at 18F, @tbaxter-18f and some others came up with a rough framework for how to most usefully document our opinions, guidelines, and decisions. One of the points of conversation included the idea that sets of opinions are less valuable than explanations of why we recommend the things we recommend, how to evaluate future tooling, and how to prevent one voice from owning an entire set of documents.

The front end guide seems like a good place to try these guidelines out and see if it gives us something that is more valuable than what we've got. The current form is almost impossible to maintain properly, especially given the fluctuations in the number of front end developers at 18F. Rather than devote several entire pages to "how to write your CSS," what if it became a tool for deciding how to write CSS yourself? What if we focused on tools that people could use even as technology changes, without having to update the documentation every time a new framework comes in vogue?

This is an experiment to see what such a rewrite would entail, and, as such, I'd love feedback and conversation around it.

hbillings · 2019-07-19T22:53:55Z

pages/index.md

-should feel comfortable developing and implementing client-side
-interactions and frameworks using semantic HTML5 and JavaScript, and
-should be able to help with debugging, testing, and performance
-optimization of the code base.


I'm torn about deleting this. On one hand, we haven't had front end designers at 18F for nearly two years. On the other hand, it feels valuable to define what we expect from front end developers (and what we don't expect). Perhaps that definition process is one that we should go through again new, though?

I think we should keep the bit about front-end developers.

hbillings · 2019-07-19T22:56:17Z

pages/js/frameworks.md

+* [Webpack](https://www.npmjs.com/package/webpack) and [Babel](https://babeljs.io/) for compiling our Javascript
+
+However, we are not dogmatic about React - we just vastly prefer it. Here are some other popular frameworks that have been used at 18F and some of their key characteristics.
+


Brought this over from the ancient PR that never got merged, just to have something to work with.

I still think, especially given people's concerns about Facebook, that we should say "React or React-like" frameworks.

I'd also feel comfortable being more dogmatic about it, and say "Use a react-like framework unless you have a compelling reason not to, such as the partner already using another framework". I just think the ramp-up time for developers diving into one person's fave framework from six months ago is much greater than any benefit from that framework in most cases.

Unless we have a strong second choice, I'd be happy dropping the angular and Backbone sections, too.

hbillings · 2019-07-19T22:57:06Z

pages/web-components.md

@@ -1,54 +0,0 @@
---


This page hasn't been updated in years, reads in first person, and has outdated takes in it. If we want to recommend a certain web component ideology, we need to do it fresh.

hbillings · 2019-07-19T23:00:57Z

pages/css/css.md

-The purpose of the CSS coding styleguide is to create consistent CSS or
-preprocessor CSS code across 18F. The styleguide should be treated as a guide
-&mdash; rules can be modified according to project needs.
+The purpose of the CSS coding styleguide is to help 18F developers make decisions about CSS tools and implementations. The goal of this guide is not to be dogmatic, but to explain how and why we recommend certain approaches, and to help developers make their own decisions for their individual projects.


The guide hasn't created consistency, so it seems a bit pompous to suggest that that's the goal.

I think we should be dogmatic, where being dogmatic is warranted. We should just say why we care.

For example, at this point, I'm fairly comfortable saying atomic CSS should not be used for long-lived code unless the partner is already using it and you're adopting their house style. It's just too difficult to pick through when you want to make changes, and unfamiliar to too many partners.

hbillings · 2019-07-20T03:27:20Z

pages/css/architecture.md

+In general, 18F recommends using a modular approach (specifically, [modified BEM])
+to provide consistency and scalability to larger apps. However, for some applications
+(such as a rapid prototype), an atomic architecture may make more sense. Below are 
+some considerations for choosing an architecture.


I wanted to get the actionable, "we generally recommend this" bit out in front of any ideological postulation.

hbillings · 2019-07-20T03:28:09Z

pages/css/architecture.md

+Modular architectures are very helpful for a few different kinds of projects:
+- larger, more complex sites with reusable components
+- sites maintained and built by multiple engineers
+- production sites that will be handed off to partner teams or vendors


This bit here is my stab at documenting why you might choose a modular system. Very open to additions/criticisms.

Should we acknowledge that yes, it's ugly, clunky and tends to break the cascade, but it's ugly, clunky and tends to break the cascade in well-known, widely used and predictable ways?

hbillings · 2019-07-20T03:29:36Z

pages/css/architecture.md

@@ -50,46 +56,10 @@ lib/neat.scss
 _overrides.scss
 ```

-For the `util`, `typography`, `elements`, and `overrides` files, once they grow
-too large (300 lines or more) in size, split them into their own folder with
-sub files.


"Too large" is a matter of opinion. I've literally never done this myself and have not seen it on a project in the wild.

hbillings · 2019-07-20T03:30:10Z

pages/css/architecture.md

-```
-
-
-## Importing


WTF is this doing in this section. Moved to "Specificity" for now.

I think it was attempting to show how the files should be organized for predictability and findability, which seems useful, but awkward here.

hbillings · 2019-07-20T03:31:19Z

pages/css/architecture.md

- Move next to overrides, possibly with !important rules.
- Import alphabetically.
- Only modify import order for groups of files, not specific files.
+## Atomic architecture


Help, I don't know what to write about atomic CSS because I can't stop hating it long enough to figure it out. :-p We should do some user interviews with folks like @hursey013 who have used/appreciated atomic CSS to figure out what they find it useful for.

Can't help you. I think it's only suitable for prototypes.

tbaxter-18f · 2019-07-22T12:29:25Z

pages/css/architecture.md

-navs, and positioning structures like insets, island, and enclosure.  From
-here, modules are built with these components. This architecture also attempts
-to keep the specificity trend in an upwards curve as you move down in the file
+In general, 18F recommends using a modular approach (specifically, [modified BEM])


I'd suggest our first suggestion would be "Use USWDS" wouldn't it?

tbaxter-18f · 2019-07-22T12:31:44Z

pages/css/architecture.md

 (more on this to come).

- Start with an elements file for all tag rules (a, h1-h5, p, \*, html, body).
+A few helpful things to keep in mind when building out a modular architecture:
+- Start with an elements file for all tag rules (`a`, `h1`-`h5`, `p`, `*`, `html`, `body`).


Why?

I don't think it's a bad idea, it just feels like a fairly strong opinion to not have a reason.

tbaxter-18f · 2019-07-22T12:32:49Z

pages/css/architecture.md

 - Create more specific structure with modules. For instance, if the logo image
  and text needs very specific treatment, use a module.
-  - Build modules from components through mixins, extends, and HTML.
-  - Modules can have higher specificity, it’s fine to use deeper nesting.
+  - Build modules from components through Sass mixins, extends, and HTML.


Do we have an opinion on mixin vs extend? I know a lot of folks do :-)

tbaxter-18f · 2019-07-22T12:35:40Z

pages/css/architecture.md

@@ -3,36 +3,42 @@ title: Architecture
 permalink: /css/architecture/
 sidenav: css
 ---
-# Architecture
+# Choosing a CSS methodology and architecture


I think my strongest opinion when it comes to our CSS is that we're either writing a quick throwaway prototype or something we intend to hand over and have our partner maintain, and we need to figure that out and behave accordingly from the get-go. For the former, I don't care what you write or how you write it, or if you follow any methodology at all beyond the mad scientist voices in your head. For the latter, I don't care how smart you are, you can't make the deliverable smarter than their average developer.

jeremiak and others added 3 commits March 9, 2018 14:19

Update frameworks.md to suggest using React

959b87a

bring in React

a97947a

remove front end dev/designer descriptions

c619f55

hbillings commented Jul 19, 2019

View reviewed changes

remove web components page

e16afb5

hbillings commented Jul 19, 2019

View reviewed changes

rewrite css page

2735116

hbillings commented Jul 19, 2019

View reviewed changes

rework architecture section

90795d9

hbillings commented Jul 20, 2019

View reviewed changes

tbaxter-18f reviewed Jul 22, 2019

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP][Experiment] Make the guide as a tool for decision-making, rather than a set of opinions #213

[WIP][Experiment] Make the guide as a tool for decision-making, rather than a set of opinions #213

hbillings commented Jul 19, 2019

hbillings Jul 19, 2019

tbaxter-18f Jul 22, 2019

hbillings Jul 19, 2019

tbaxter-18f Jul 22, 2019

hbillings Jul 19, 2019

hbillings Jul 19, 2019

tbaxter-18f Jul 22, 2019

hbillings Jul 20, 2019

hbillings Jul 20, 2019

tbaxter-18f Jul 22, 2019

hbillings Jul 20, 2019

hbillings Jul 20, 2019

tbaxter-18f Jul 22, 2019

hbillings Jul 20, 2019

tbaxter-18f Jul 22, 2019

tbaxter-18f Jul 22, 2019

tbaxter-18f Jul 22, 2019

tbaxter-18f Jul 22, 2019

tbaxter-18f Jul 22, 2019

		* [Webpack](https://www.npmjs.com/package/webpack) and [Babel](https://babeljs.io/) for compiling our Javascript

		However, we are not dogmatic about React - we just vastly prefer it. Here are some other popular frameworks that have been used at 18F and some of their key characteristics.

[WIP][Experiment] Make the guide as a tool for decision-making, rather than a set of opinions #213

Are you sure you want to change the base?

[WIP][Experiment] Make the guide as a tool for decision-making, rather than a set of opinions #213

Conversation

hbillings commented Jul 19, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment