Skip to content
This repository was archived by the owner on Feb 15, 2020. It is now read-only.

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

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
959b87a
Update frameworks.md to suggest using React
jeremiak Mar 9, 2018
a97947a
bring in React
Jul 19, 2019
c619f55
remove front end dev/designer descriptions
Jul 19, 2019
e16afb5
remove web components page
Jul 19, 2019
2735116
rewrite css page
Jul 19, 2019
90795d9
rework architecture section
Jul 20, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions pages/css/css.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,4 @@ sidenav: css
---

# CSS
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
— 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.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

30 changes: 1 addition & 29 deletions pages/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,32 +3,4 @@ title: 18F Front-End Guide
permalink: /
---
Welcome to the 18F Front-End Guide! This is where we keep all of our
guidelines for front-end design and development.

## What is front end?

The Front-End Guild did a series of exercises to determine the
fundamental differences between the front-end design and front-end
developer roles at 18F. Using [some of our own research
methods](https://methods.18f.gov), the Front-End Guild came up with
the following recommendations on knowing the difference between the
two disciplines:

**Front-end designers** design, write, and implement the
presentational code base for websites and applications. They should
have a clear understanding of design fundamentals and systems, such
as interface style guides, responsive design, grid systems, front-end
frameworks, and accessibility best practices. Front-end designers
should feel comfortable creating and implementing design systems
using semantic HTML5, CSS/Sass and be able to assist in debugging
this aspect of the code base.

**Front-end developers** architect, write, and implement the
functional code base for websites and applications. They should have
a clear understanding of client-side render and response, such as
HTTP methods, API consumption, the browser loading/rendering
pipeline, and accessibility best practices. Front-end developers
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.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

guidelines for front-end design and development.
9 changes: 8 additions & 1 deletion pages/js/frameworks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,14 @@ permalink: /javascript/frameworks/
sidenav: js
---
# Frameworks

**We recommend using [React]() for projects when possible.** As a team, we enjoy using React because it has a strong component model, enables easy server side rendering, and faciliates debugging by making the UI elements a function of the application state. React is most akin to the "view layer" in an MVC (Model-View-Controller) architecture and is frequently used with some other libraries. In our projects, we tend to use:

* [Redux](https://www.npmjs.com/package/redux) for managing state
* [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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

## Angular
AngularJS (commonly referred to as "Angular") is an open-source web application framework maintained by Google and by a community of individual developers and corporations to address many of the challenges encountered in developing single-page applications ([Wikipedia](http://en.wikipedia.org/wiki/AngularJS)).

Expand Down Expand Up @@ -61,7 +69,6 @@ Backbone.js is a JavaScript library with a RESTful JSON interface and is based o
- Since it has very little structure, inexperienced programmers can easily create unmaintainable code with Backbone.
- Designed primarily for REST data.


## React
React (sometimes styled React.js or ReactJS) is an open-source JavaScript library for creating user interfaces that aims to address challenges encountered in developing single-page applications ([Wikipedia](https://en.wikipedia.org/wiki/React_(JavaScript_library))).

Expand Down
54 changes: 0 additions & 54 deletions pages/web-components.md
View file
Open in desktop

This file was deleted.