74 | ```
75 |
76 | Don't create elements inside elements. If you find yourself needing this, consider converting your element into a block.
77 |
78 | We _don't_ do this:
79 | ```css
80 | .c-alert-box__close__button
81 | ```
82 |
83 | Choose your modifiers wisely. These two rules have very different meaning:
84 | ```css
85 | .c-block--modifier .c-block__element { color: red; }
86 | .c-block__element--modifier { color: red; }
87 | ```
88 |
89 | Don't nest class names when using a preprocessor. Here are a few reasons why:
90 |
91 | 1. It prevents from being able to find the class names easily
92 | 2. It hinders developers understanding the context that they are working on
93 | 3. When reviewing a pull request, it requires extra effort to see the actual
94 | selector and to do a proper review
95 |
96 | We _do_ this:
97 |
98 | ```css
99 | .c-block { padding: 24px; }
100 |
101 | .c-block--modifier { padding: 12px; }
102 |
103 | .c-block__element { color: white; }
104 |
105 | .c-block__element--modifier { color: black }
106 | ```
107 |
108 | We _don't_ do this:
109 |
110 | ```css
111 | .c-block {
112 | padding: 24px;
113 |
114 | &--modifier {
115 | padding: 12px;
116 | }
117 |
118 | &__element {
119 | color: white;
120 |
121 | &--modifier {
122 | color: black;
123 | }
124 | }
125 | }
126 | ```
127 |
--------------------------------------------------------------------------------
/css/config/.stylelintrc:
--------------------------------------------------------------------------------
1 | {
2 | "rules": {
3 | "at-rule-empty-line-before": [ "always", {
4 | "except": ["blockless-group"]
5 | } ],
6 | "block-closing-brace-newline-after": "always",
7 | "block-closing-brace-newline-before": "always-multi-line",
8 | "block-closing-brace-space-before": "always-single-line",
9 | "block-no-empty": true,
10 | "block-opening-brace-newline-after": "always-multi-line",
11 | "block-opening-brace-space-after": "always-single-line",
12 | "block-opening-brace-space-before": "always",
13 | "color-hex-case": "lower",
14 | "color-hex-length": "short",
15 | "color-no-invalid-hex": true,
16 | "comment-empty-line-before": [ "always", {
17 | "except": ["first-nested"]
18 | }],
19 | "declaration-bang-space-after": "never",
20 | "declaration-bang-space-before": "always",
21 | "declaration-block-semicolon-newline-after": "always-multi-line",
22 | "declaration-block-semicolon-space-after": "always-single-line",
23 | "declaration-block-semicolon-space-before": "never",
24 | "declaration-block-single-line-max-declarations": 0,
25 | "declaration-colon-newline-after": "always-multi-line",
26 | "declaration-colon-space-after": "always-single-line",
27 | "declaration-colon-space-before": "never",
28 | "function-calc-no-unspaced-operator": true,
29 | "function-comma-newline-after": "always-multi-line",
30 | "function-comma-space-after": "always-single-line",
31 | "function-comma-space-before": "never",
32 | "function-parentheses-newline-inside": "always-multi-line",
33 | "function-parentheses-space-inside": "never-single-line",
34 | "function-whitespace-after": "always",
35 | "indentation": "tab",
36 | "max-empty-lines": 1,
37 | "media-feature-colon-space-after": "always",
38 | "media-feature-colon-space-before": "never",
39 | "media-feature-range-operator-space-after": "always",
40 | "media-feature-range-operator-space-before": "always",
41 | "media-query-list-comma-newline-after": "always-multi-line",
42 | "media-query-list-comma-space-after": "always-single-line",
43 | "media-query-list-comma-space-before": "never",
44 | "media-query-parentheses-space-inside": "never",
45 | "no-eol-whitespace": true,
46 | "no-missing-eof-newline": true,
47 | "number-leading-zero": "always",
48 | "number-no-trailing-zeros": true,
49 | "number-zero-length-no-unit": true,
50 | "rule-no-shorthand-property-overrides": true,
51 | "rule-non-nested-empty-line-before": "always-multi-line",
52 | "rule-trailing-semicolon": "always",
53 | "selector-combinator-space-after": "always",
54 | "selector-combinator-space-before": "always",
55 | "selector-list-comma-newline-after": "always",
56 | "selector-list-comma-space-before": "never",
57 | "string-quotes": "single",
58 | "value-list-comma-newline-after": "always-multi-line",
59 | "value-list-comma-space-after": "always-single-line",
60 | "value-list-comma-space-before": "never"
61 | }
62 | }
--------------------------------------------------------------------------------
/css/house-style.md:
--------------------------------------------------------------------------------
1 | # CSS style guide
2 |
3 | We namespace our CSS as detailed in our [how we write CSS](how-we-write-css.md) guide. For the purposes of the examples here, we will use the `component` namespace.
4 |
5 | - [General principles](#general-principles)
6 | - [Code style](#code-style)
7 | - [Linting](#linting)
8 | - [Preprocessors](#preprocessors)
9 | - [Nesting](#nesting)
10 |
11 | ## General principles
12 |
13 | We write our CSS using design patterns that aim to maximise maintainability and reuse; See our [house style document](../practices/house-style.md) to understand the rationale behind enforcement of style.
14 |
15 | ## Code style
16 |
17 | Avoid using HTML tags in CSS selectors. And always prefer using a class over HTML tags (with some exceptions)
18 |
19 | We _don't_ do this
20 | ```scss
21 | div {}
22 | div.c-modal {}
23 | ```
24 |
25 | We do this:
26 | ```scss
27 | .c-modal {}
28 | ```
29 |
30 | Don't use [ids in selectors](http://csswizardry.com/2011/09/when-using-ids-can-be-a-pain-in-the-class/)
31 |
32 | We _don't_ do this:
33 | ```scss
34 | #header {}
35 | ```
36 |
37 | We do this:
38 | ```scss
39 | .c-header {}
40 | ```
41 |
42 | Avoid using `margin-top`. Vertical margins [collapse](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Mastering_margin_collapsing). Always prefer `padding-top` or `margin-bottom` on preceding elements
43 |
44 | We _don't_ do this:
45 | ```scss
46 | .c-list__item {
47 | margin-top: 10px;
48 | }
49 | ```
50 |
51 | We do this:
52 | ```scss
53 | .c-list__item {
54 | padding-top: 10px;
55 | }
56 |
57 | /* or */
58 |
59 | .c-list__item {
60 | margin-bottom: 10px;
61 | }
62 | ```
63 |
64 | Avoid shorthand properties, if you aren't setting all the values in the property. This applies to all properties with a shorthand: border, margin, padding, font, etc. Use your judgement on this, as there are exceptions.
65 |
66 | We _don't_ do this:
67 | ```scss
68 | .c-modal {
69 | // overrides other values encapsulated by the shorthand property.
70 | // In this case, background-image and its associative properties are set to “none”
71 | background: $white;
72 | border: 1px;
73 | }
74 | ```
75 |
76 | We do this:
77 | ```scss
78 | .c-modal {
79 | background-color: $white;
80 | border-width: 1px;
81 | }
82 | ```
83 |
84 | Don't use `!important`. If you must, leave a comment, and prioritise resolving specificity issues before resorting to `!important`.
85 |
86 | ### Linting
87 |
88 | Static analysis tools like linters can flag programming errors, bugs and stylistic errors, making your code more robust, readable and maintainable.
89 |
90 | CSS code (not compiled) should be linted with [styleLint](https://github.com/stylelint/stylelint). You can find _an example_ config file in the [config directory](config).
91 |
92 | Sass code should be linted with [Stylelint](https://stylelint.io/) using the [Springer Nature
93 | `stylelint-config`](https://github.com/springernature/stylelint-config-springernature). This configuration allows us to maintain consistency between different projects.
94 |
95 | You can check the [README](https://github.com/springernature/sasslint-config-springernature/blob/main/README.md) for details about installing and configuring the tools.
96 |
97 | ## Preprocessors
98 |
99 | Our preferred CSS preprocessor is [Sass](https://sass-lang.com) using the SCSS syntax. Find out about [how we write CSS](how-we-write-css.md).
100 |
101 | ### Nesting
102 |
103 | Nesting selectors increases specificity, meaning that overriding any CSS set therein needs to be targeted with an even more specific selector. This quickly becomes a significant maintenance issue, which makes excessive nesting [a bad idea](http://www.sitepoint.com/beware-selector-nesting-sass/). It can easily be avoided by using smart class naming. Avoid nesting selectors more than **3 levels** deep, and prefer using nesting as a convenience to extend the parent selector over targeting nested elements.
104 |
105 | If possible, try and avoid using nesting for anything other than:
106 |
107 | **Pseudo selectors and state selectors**. We do this:
108 | ```scss
109 | a {
110 | &:hover {
111 | text-decoration: underline;
112 | }
113 | &:focus {
114 | outline: 1px dashed #000;
115 | }
116 | }
117 |
118 | span {
119 | &::before {
120 | content: '\2022';
121 | }
122 | }
123 | ```
124 |
125 | **Javascript-only style enhancements**. We do this:
126 | ```scss
127 | .c-class {
128 | display: block;
129 |
130 | .js & {
131 | display: flex;
132 | }
133 | }
134 | ```
135 | > _Read more about [how to add the `.js` class](../practices/javascript-styling.md)_
136 |
137 | **Inline html tags within other elements**. We do this:
138 | ```scss
139 | .c-class {
140 | span {}
141 | em {}
142 | small {}
143 | /* etc */
144 | }
145 | ```
146 |
147 | **Media queries**. We nest media queries and position the media queries after the CSS declarations for that block.
148 |
149 | We _don't_ do this:
150 | ```scss
151 | .c-header__journal-title {
152 | @include media-query('md') {
153 | font-size: 1.25rem;
154 | }
155 |
156 | @include media-query('lg') {
157 | font-size: 1.5rem;
158 | }
159 |
160 | font-size: 1rem;
161 | color: #000;
162 | }
163 | ```
164 |
165 | We do this:
166 | ```scss
167 | .c-header__journal-title {
168 | font-size: 1rem;
169 | color: #000;
170 |
171 | @include media-query('md') {
172 | font-size: 1.25rem;
173 | }
174 |
175 | @include media-query('lg') {
176 | font-size: 1.5rem;
177 | }
178 | }
179 | ```
180 |
181 | **Breakpoints**
182 | These should be nested within the relevant parent using `@include`.
183 |
184 | One exception to these rules is targeting a BEM element from within a nested block rule. See the [BEM documentation](bem-css.md) for more information on BEM and nesting.
185 |
--------------------------------------------------------------------------------
/git/README.md:
--------------------------------------------------------------------------------
1 | # git
2 |
3 | We use git as a our version control system.
4 |
5 | * [git](git.md)
6 | * [Semver](semver.md)
7 |
8 | [Main table of contents](../README.md#table-of-contents)
9 |
--------------------------------------------------------------------------------
/git/git.md:
--------------------------------------------------------------------------------
1 | # Git
2 |
3 | - [Repository names](#repository-names)
4 | - [Working with branches](#working-with-branches)
5 | - [Commit messages](#commit-messages)
6 | - [Pull requests](#pull-requests)
7 | - [Versioning](#versioning)
8 |
9 | ## Repository names
10 |
11 | We use a standard naming format for our Git repositories. Repository names are _lowercase-hyphenated_ (all lowercase, words separated by a hyphen), and begin with "frontend" followed by your project name.
12 |
13 | We _don't_ do this:
14 |
15 | ```
16 | front-end-project-name
17 | front-end-projectname
18 | project-name-front-end
19 | project-name-frontend
20 | ```
21 |
22 | We do this:
23 |
24 | ```
25 | frontend-project-name
26 | ```
27 |
28 | ## Working with branches
29 |
30 | Create a local branch based off the default branch. For this example, let's assume the default branch is called `main`.
31 |
32 | Follow [Continous Delivery](https://martinfowler.com/bliki/ContinuousDelivery.html) and [Continuous Integration](https://martinfowler.com/articles/continuousIntegration.html) principles as much as is reasonable (given the constraints of your team). Branches should be:
33 |
34 | * As short lived as possible.
35 | * _Atomic_, i.e. one unit of work that can't be sensibly subdivided.
36 | * They should contain their own tests.
37 | * They should be releasable independently.
38 | * As limited in scope as possible. Large pull requests are hard to review and can be painful to merge. Also, once merged & a bug is traced back to that commit, they are much harder to debug.
39 |
40 | When your work is almost complete, `git rebase main` or merge -- especially if other people are working on the same code. Avoid merge pain by;
41 |
42 | * _talking to your team_ to divide work across files sensibly & co-ordinate merges if required.
43 | * `git pull origin main` and rebase or merge often.
44 | * make sure branches are short-lived! (Did we mention that branches should be short-lived?)
45 |
46 | When the unit of work is complete and tests pass, stage your changes and commit them.
47 |
48 | ## Commit messages
49 |
50 | Your commit messages are your personal legacy. They are the record of what you've done to a codebase and more importantly, *why*. A good commit message is composed of a summary line or shortlog, and a description.
51 |
52 | * The summary line should be [50 characters or less](http://stopwritingramblingcommitmessages.com/), followed by a blank line.
53 | * Use present tense rather than past tense when referring to changes introduced by commit in question. For example, use "Update request library" instead of "Updated request library". Imagine your commit message has to make sense prefaced with _"If applied, this commit will..."_.
54 | * Summarize only the change itself in the summary line, not the bug or effects/benefits (that goes in description).
55 | * Unhelpful messages like "Update" or "Bugfix" are... _unhelpful_. Please explain a little more. Bear in mind that the commit message should allow you or anyone else to understand the changes, both now and in a year's time.
56 | * If your work is part of a ticket, include the ticket number in the commit message, but don't only use the ticket number as the commit message. Otherwise this just makes life hard for your colleagues to understand what the change was for. The git log should be all they need to read. You may also include a link to the bug after the description, separated by one blank line.
57 | * Add a description, if necessary, as detailed as you need. Make sure that lines wrap at 72 characters.
58 |
59 | A few blog posts on writing better commit messages:
60 |
61 | * [5 Useful Tips for a Better Commit Message](https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message)
62 | * [A Note About Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
63 | * [Git Commit](http://chris.beams.io/posts/git-commit/)
64 | * [Writing Good Commit Messages](https://github.com/erlang/otp/wiki/Writing-good-commit-messages)
65 | * [Better Commit Messages with a `.gitmessage` Template](https://robots.thoughtbot.com/better-commit-messages-with-a-gitmessage-template)
66 | * [GNOME project - Guidelines for Commit Messages](https://wiki.gnome.org/Git/CommitMessages)
67 |
68 | Once your work is committed, submit a [pull request](https://help.github.com/articles/using-pull-requests/).
69 |
70 | ## Pull requests
71 |
72 | We use pull requests to review code. [GitHub's pull request reviews feature](https://help.github.com/articles/about-pull-request-reviews/) blocks merging of code until it's been reviewed. It may or may not be enabled on a repository, at the discretion of the individual team. You should submit your pull requests for review regardless of whether or not this feature is enabled.
73 |
74 | 1. Ask for a code review in Slack.
75 | 2. A colleague (or multiple colleagues) other than the author will review the pull request. They will make comments and ask questions directly in the GitHub web interface. See the [Code review guide](../practices/code-review.md) to see what reviewers are looking for.
76 | 3. When satisfied, the reviewer(s) will approve the pull request, so that your code can be merged.
77 | 4. Give your code one last visual check in github.
78 | 5. Double-check the commit message -- and any commit message detail -- then **"Squash & Merge" commits via github**. We do not want lots of "work in progress" commits cluttering the commit history on the default branch. _One unit of work, one commit._
79 |
80 | Your work is now merged, good job! Delete your remote branch, and delete your local branch too, if you want.
81 |
82 | ## Versioning
83 |
84 | Our open source projects are versioned with [SemVer](semver.md). Check our [Open Source support](../practices/open-source-support.md) guide for details on how to version and release an update to an open source project.
85 |
86 | Closed source projects may use different versioning practices.
87 |
--------------------------------------------------------------------------------
/git/semver.md:
--------------------------------------------------------------------------------
1 | # SemVer
2 |
3 | * [What is SemVer](#what-is-semver)
4 | * [Why we use SemVer](#why-we-use-semver)
5 | * [Common concerns](#common-concerns)
6 | * [How can I trust that things aren’t going to break with a minor or patch release update?](#how-can-i-trust-that-things-arent-going-to-break-with-a-minor-or-patch-release-update)
7 | * [The version number is getting really big really quickly!](#the-version-number-is-getting-really-big-really-quickly)
8 | * [Find out more:](#find-out-more)
9 |
10 |
11 | ## What is SemVer
12 |
13 | SemVer is a way of versioning software in the format of MAJOR.MINOR.PATCH:
14 |
15 | * MAJOR version when you make breaking changes,
16 | * MINOR version when you add functionality in a backwards-compatible manner for any specific MAJOR version, and
17 | * PATCH version when you make backwards-compatible bug fixes to any specific MAJOR.MINOR version.
18 |
19 | This means that any time you release a new MAJOR release, the minor and patch values reset to 0, and the same is true of the patch value when making a MINOR release.
20 |
21 | For more information about how SemVer is defined, please see: http://semver.org/
22 |
23 | ## Why we use SemVer
24 |
25 | SemVer allows us to keep a consistent numbering scheme to ensure that going forward we can maintain compatibility with all system and platform components. It also allows us to upgrade dependencies with the confidence that things won’t break.
26 |
27 | SemVer enables us to ensure that once something is committed we can be confident that any version remains unique.
28 |
29 | ## Common concerns
30 |
31 | ### How can I trust that things aren’t going to break with a minor or patch release update?
32 |
33 | Like any practice, SemVer can be let down by people not using it correctly (like releasing a breaking change under a minor version rather than a major). It’s the responsibility of the person upgrading to ensure that the upgrade is appropriate and compatible.
34 |
35 | ### The version number is getting really big really quickly!
36 |
37 | When a piece of software under heavy development many major/minor releases may happen in quick succession, so your version might start to look like 23.2.0 or 3.34.1. THAT’S OKAY! If that’s a true representation of what has happened in the code, then it’s appropriate that the version number reflects that.
38 |
39 | What _might_ be a worry is if your version looked like 2.1.45 - did you really release 45 patches/bug fixes in a row without adding any new features?
40 |
41 | ## Find out more:
42 |
43 | * [Canonical source of info](http://semver.org/)
44 | * [How we version and release our open-source software](../practices/open-source-support.md)
45 | * [What is Semantic Versioning (SemVer)?](https://abdulapopoola.com/2015/10/26/what-is-semver/)
46 |
--------------------------------------------------------------------------------
/javascript/README.md:
--------------------------------------------------------------------------------
1 | # JavaScript
2 |
3 | We use JavaScript both in the client and on the server.
4 |
5 | * [House style](house-style.md)
6 |
7 | [Main table of contents](../README.md#table-of-contents)
8 |
--------------------------------------------------------------------------------
/learning/README.md:
--------------------------------------------------------------------------------
1 | # Learning resources
2 |
3 | In this section we offer curated lists of learning resources that people can use to get started or improve their knowledge of accessibility or web performance.
4 |
5 | * [Accessibility](web-accessibility.md)
6 | * [Web performance](web-performance.md)
7 |
8 | [Main table of contents](../README.md#table-of-contents)
9 |
--------------------------------------------------------------------------------
/learning/web-accessibility.md:
--------------------------------------------------------------------------------
1 | # Web accessibility
2 |
3 | This is a list of different resources that we offer to people interested in knowing more about web accessibility.
4 |
5 | Udacity have published an [excellent free course on Web Accessibility](https://www.udacity.com/course/web-accessibility--ud891) with Google engineers Alice Boxhall and Rob Dodson.
6 |
7 | The Financial Times have produced an [accessibility tip sheet](https://ft-interactive.github.io/accessibility/index.html).
8 |
9 | The Government Digital Service frequently publishes excellent resources. Some highlights are:
10 |
11 | * [We're making accessibility clearer and easier](https://gds.blog.gov.uk/2017/10/23/were-making-accessibility-clearer-and-easier/)
12 | * [Making your service accessible: an introduction](https://www.gov.uk/service-manual/helping-people-to-use-your-service/making-your-service-accessible-an-introduction)
13 |
--------------------------------------------------------------------------------
/learning/web-performance.md:
--------------------------------------------------------------------------------
1 | # Web performance
2 |
3 | This is a list of different resources that we offer to people interested in knowing more about web performance.
4 |
5 | ## Online courses
6 |
7 | For people wanting to learn about web performance we recommend to have a look at the following courses:
8 |
9 | * ["Lightning-fast web performance"](https://scottjehl.com/lfwp/) by Scott Jehl is an excellent short introductory course that has been recently made free.
10 | * ["Web Performance Fundamentals"](https://frontendmasters.com/courses/web-perf/) by Todd Gardner covers things in more detail. A subscription to Frontend Masters is required.
11 |
12 | ## Books
13 |
14 | The following books can be used as refererence. Some of them have been published for a while so not all advice may be applicable today, but they are still very useful to improve knowledge of a particular subject.
15 |
16 | * "High Performance Web Sites" by Steve Souders: https://learning.oreilly.com/library/view/high-performance-web/9780596529307/
17 | * "Even Faster Web Sites" by Steve Souders: https://learning.oreilly.com/library/view/even-faster-web/9780596803773/
18 | * "High Performance Browser Networking" by Ilya Grigorik: https://hpbn.co/
19 | * "HTTP/2 in Action" by Barry Pollard: https://learning.oreilly.com/library/view/http-2-in-action/9781617295164/
20 | * "Using WebPageTest" by Rick Viscomi, Andy Davies & Marcel Duran: https://learning.oreilly.com/library/view/using-webpagetest/9781491902783/
21 | * "Time Is Money" by Tammy Everts: https://learning.oreilly.com/library/view/time-is-money/9781491928783/
22 |
23 | ## Videos
24 |
25 | * Catchpoint frequently releases videos showcasing new features of WebPageTest, or Twitch streams of their performance auditing sessions:
26 | https://www.youtube.com/channel/UC5CqJ9V7cQddZDf1DKXcy7Q/featured
27 | * The London Web Performance Group has a youtube channel with most of their talks: https://www.youtube.com/user/ldnwebperf/videos
28 |
29 | ## Other resources
30 |
31 | * Google has three collections of web performance-related material available on their web.dev site: https://web.dev/learn/#collections
32 |
--------------------------------------------------------------------------------
/markup/README.md:
--------------------------------------------------------------------------------
1 | # Markup
2 |
3 | We utilise HTML5 for compiled markup.
4 |
5 | * [House style](house-style.md)
6 |
7 | [Main table of contents](../README.md#table-of-contents)
8 |
--------------------------------------------------------------------------------
/markup/house-style.md:
--------------------------------------------------------------------------------
1 | # Markup
2 |
3 | This document outlines the way we write markup and why. See our [house style document](../practices/house-style.md) to understand the rationale behind enforcement of style.
4 |
5 | - [HTML vs XHTML](#html-vs-xhtml)
6 | - [We author HTML 5](#we-author-html-5)
7 | - [Validation](#validation)
8 | - [Do not omit optional end tags](#do-not-omit-optional-end-tags)
9 | - [Implicitly close void elements](#implicitly-close-void-elements)
10 | - [Closing elements in embedded documents](#closing-elements-in-embedded-documents)
11 | - [Form submit controls](#form-submit-controls)
12 | - [Semantics](#semantics)
13 | - [Follow the HTML 4 outline model for heading levels](#follow-the-html-4-outline-model-for-heading-levels)
14 | - [Templating language](#templating-language)
15 |
16 | ## HTML vs XHTML
17 |
18 | HTML up to 3.2 was written with SGML syntax rules. HTML 4 could be written with either SGML syntax (HTML 4.01) or XML (XHTML 1.0). [HTML 5 breaks with SGML and has two serializations](https://www.w3.org/blog/2008/01/html5-is-html-and-xml/), a new one called "html" (which looks like SGML but is not an application of SGML) and again XML (XHTML).
19 |
20 | ### We author HTML 5
21 |
22 | When a document is transmitted with an XML MIME type, such as `application/xhtml+xml`, this is intended to instruct the client to render using an XML parser, and popular contemporary clients honour this. [See HTML vs XHTML on w3.org](https://www.w3.org/TR/html5/introduction.html#html-vs-xhtml).
23 |
24 | One of the benefits of XML is its strictness -- the flip-side of this benefit is that XML is not designed to fail safely. The internet, the web, and typical web clients are however designed to fail safely. This is a philosophical difference with practical implications.
25 |
26 | In professional web development, one typically has to rely on 3rd-party code which is executed in our domain, but under which we have no real control (advertisements, tracking code, resources served from 3rd-party CDNs, etc). Additionally accidents happen, and broken code goes live. So we must think defensively and cannot rely on the validity of our documents. When XHTML is served with an `application/xhtml+xml` MIME type, any errors introduce fatal errors in the document parser and completely unusable pages are the result.
27 |
28 | So for business purposes it is impractical to serve XHTML with anything other than a `text/html` MIME type. This means the client cannot leverage an XML parser and instead uses a regular HTML parser, so any XML benefits are lost to the client. Additionally it introduces cognitive dissonance (a document which is an application of XML not being treated as such), we are serving a heavier page over an HTML 5 equivalent for no client-side benefit, and we lose some HTML features with XHTML such as [NOSCRIPT](https://www.w3.org/TR/html5/scripting-1.html#the-noscript-element) (which still appears in 3rd-party code).
29 |
30 | It is not impossible to imagine a back-end markup-generation system that only outputs XHTML, but as any valid XHTML document is essentially expressible in HTML (the reverse is not true) this should be seen as a shortcoming in the markup generator, at least as far as the client is concerned.
31 |
32 | As such it seems beneficial to choose HTML 5 over XHTML.
33 |
34 | ### Validation
35 |
36 | Do what is reasonable to ensure your documents [validate](https://validator.w3.org/).
37 |
38 | Invalid markup results in authors relying on all clients to do what they intended, not what they instructed. Clients regularly disagree on how to interpret our instructions, yet alone our intentions, so to promote consistency of execution you must do what you can to ensure your HTML is valid.
39 |
40 | Additionally, invalid HTML violates WCAG 2.1 Success Criterion [4.1.1 Parsing](https://www.w3.org/TR/WCAG21/#parsing) (Level A), and areas where your product falls short must be noted on your product's VPAT, if it has one. It's probably easier just to make sure your HTML is valid in the first place.
41 |
42 | ### Do not omit optional end tags
43 |
44 | While the HTML 4 & 5 specs allow some end tags to be omitted for _some_ non-[void elements](https://www.w3.org/TR/html5/syntax.html#void-elements), it's unreasonable to expect authors to remember which elements this applies to. Additionally this kind of inconsistency can play havok with text editors, any indentation policy, and impairs our ability to spot bugs that would otherwise offend our pattern-recognition powers.
45 |
46 | We do this:
47 |
48 | ```html
49 |
50 | foo
51 | bar
52 |
53 | ```
54 |
55 | We *don't* do this:
56 |
57 | ```html
58 |
59 | foo
60 | bar
61 |
62 | ```
63 |
64 | ### Implicitly close void elements
65 |
66 | Explicitly closing void elements (e.g. `
`) is not invalid in HTML 5. However, explicitly closing void elements is an artifact of XML serialization, not HTML 5's "html" serialization, so may introduce cognitive dissonance in authors given that we are authoring HTML 5. Additionally, explicitly closing void elements was invalid in older versions of HTML.
67 |
68 | Conversely, it may be the case that their omission impacts authors more used to writing XML, or HTML with an XML serialization. However as far as machines are concerned, they increase page weight with zero benefit.
69 |
70 | We do this:
71 |
72 | ```html
73 |
74 | ```
75 |
76 | We *don't* do this:
77 |
78 | ```html
79 |
80 | ```
81 |
82 | #### Closing elements in embedded documents
83 |
84 | Sometimes we need to embed content from different markup languages in HTML, such as
85 | [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG) or
86 | [MathML](https://developer.mozilla.org/en-US/docs/Web/MathML/).
87 |
88 | When embedding these markup languages in HTML, there is no need to specify an namespace on the root element as it will be provided by the HTML parser. See also the [SVG specs](https://svgwg.org/svg2-draft/struct.html#Namespace) and [Using MathML](https://developer.mozilla.org/en-US/docs/Web/MathML/Authoring#using_mathml).
89 |
90 | Because the namespace is provided by the HTML parser, we still do not need to explicitly close void elements.
91 |
92 | We do this:
93 |
94 | ```html
95 |
96 |
97 |
98 | ```
99 |
100 | We *don't* do this:
101 |
102 | ```html
103 |
104 |
106 | ```
107 |
108 | Conversely, if you were authoring for an XML document (including XHTML, EPUB) you would include the namespace and would therefore have to explicitly close void elements.
109 |
110 | ### Form submit controls
111 |
112 | In modern browsers, `button type="submit"` provides a superset of functionality when compared to `input type=submit`.
113 |
114 | `button` elements are much easier to style than `input` elements. You can add
115 | inner HTML content (think `
`, ``, or even `Page title
189 |
190 |
191 | Article title
192 | Article subtitle
193 |
194 |
195 |
198 | ```
199 |
200 | We *don't* do this:
201 |
202 | ```html
203 | Page title
204 |
205 |
206 | Article title
207 | Article subtitle
208 |
209 |
210 |
213 | ```
214 |
215 | ## Templating language
216 |
217 | Templates should be written using [Handlebars](http://handlebarsjs.com/).
218 |
219 | Handlebars works in the browser, Node, and has been ported to the JVM-based languages we use server-side.
220 |
221 | This enables us to share the same templates across the variety of environments we commonly use. Also Handlebars is a well-documented, stable technology with "good enough" compatibility between implementations (although handlebars helpers are an exception).
222 |
--------------------------------------------------------------------------------
/performance/README.md:
--------------------------------------------------------------------------------
1 | # Performance
2 |
3 | Performance refers to the speed in which web pages are downloaded and displayed on the user's browser.
4 |
5 | Faster page speeds have been shown to increase visitor retention and user satisfaction, especially for users with slow internet connections and those on mobile devices. Improved web performance also leads to less data travelling across the web, which in turn lowers a website's power consumption and environmental impact.
6 |
7 | - [Advertising](advertising.md)
8 | - [Browser caching](browser-caching.md)
9 | - [Font loading](font-loading.md)
10 | - [Images](images.md)
11 | - [Performance checklist](performance-checklist.md)
12 |
13 | [Main table of contents](../README.md#table-of-contents)
14 |
--------------------------------------------------------------------------------
/performance/advertising.md:
--------------------------------------------------------------------------------
1 | # Advertising
2 |
3 | - [Ethical](#ethical)
4 | - [Accessibility](#accessibility)
5 | - [Performance](#performance)
6 | - [References](#references)
7 |
8 | These guidelines are based on ethical, [accessibility](../accessibility/README.md) and performance recommendations and best practices.
9 |
10 | ## Ethical
11 |
12 | * Do use clear, intelligible, and unambiguous information.
13 | * Don't use ads that are misleading. For example, "trick banners" that look like part of the operating system UI.
14 | * Don't use ads that advertise businesses that participate in spammy or scammy practices.
15 | * Don't use images that convey a false sense of urgency.
16 | * Don't advertise products with obvious exaggerations or dubious claims that are impossible to prove.
17 | * Don't advertise "free" products or services that have hidden costs or charges.
18 | * Don't advertise gambling, alcohol and tobacco.
19 | * Don't use [pop-under ads](https://en.wikipedia.org/wiki/Pop-up_ad#Pop-under_ads).
20 | * Adverts must not contain spyware, malware or any software that results in an unexpected or deceptive experience. This includes links to sites containing these products.
21 |
22 | ## Accessibility
23 |
24 | * Don't use ads that make use of fast animations or flashing content.
25 | * The ad content must have clearly defined borders and not be confused with normal page content.
26 | * Audio or video in ads must be user initiated. A control must be included in order to allow for audio/video initiation and stop.
27 |
28 | All advertising must also comply with the rest of our [accessibility guidelines](../accessibility/06-accessibility-checklist.md).
29 |
30 | ## Performance
31 |
32 | * Do load ads asynchronously.
33 | * Don't use ads that add a significant size to the page.
34 | * Do use a maximum of 15 file requests for initial file load, as per the [IAB display advertising guidelines](https://www.iab.com/guidelines/iab-display-advertising-guidelines/).
35 | * All assets must be packaged together for delivery. All assets should be delivered in compressed format (e.g. GZIP).
36 |
37 | ## References
38 |
39 | * IAB Display Advertising Guidelines
40 | [https://www.iab.com/guidelines/iab-display-advertising-guidelines/](https://www.iab.com/guidelines/iab-display-advertising-guidelines/)
41 |
42 | * UK Code of Non-broadcast Advertising and Direct & Promotional Marketing (CAP Code) [https://www.asa.org.uk/codes-and-rulings/advertising-codes/non-broadcast-code.html](https://www.asa.org.uk/codes-and-rulings/advertising-codes/non-broadcast-code.html)
43 |
44 | * Advertising Standards Authority (ASA)
45 | [https://www.asa.org.uk/](https://www.asa.org.uk/)
46 |
47 | * Facebook Advertising Policies
48 | [https://www.facebook.com/policies/ads](https://www.facebook.com/policies/ads)
49 |
50 | * Pinterest Advertising Standards
51 | [https://about.pinterest.com/en/advertising-standards](https://about.pinterest.com/en/advertising-standards)
52 |
53 | * LinkedIn Advertising Guidelines
54 | [https://www.linkedin.com/legal/sas-guidelines](https://www.linkedin.com/legal/sas-guidelines)
55 |
--------------------------------------------------------------------------------
/performance/browser-caching.md:
--------------------------------------------------------------------------------
1 | # Browser caching
2 |
3 | - [HTML Markup](#html-markup)
4 | - [CSS, JS and Images](#css-js-and-images)
5 | - [General](#general)
6 | - [Further resources](#further-resources)
7 |
8 | ## HTML Markup
9 |
10 | * Serve these with a `Cache-Control: no-cache` header. This will instruct the browser to cache locally but only after checking with the server that the content hasn’t changed. Note that `no-cache` does NOT mean "don’t cache", rather it tells the browser to always revalidate when the resource is requested. `no-store` tells the browser not to cache at all, which isn’t usually desirable.
11 | * See [Caching best practices](https://jakearchibald.com/2016/caching-best-practices/) for more information.
12 |
13 | ## CSS, JS and Images
14 |
15 | * Set a long `max-age` eg: `Cache-Control: max-age: 31536000` (one year). The `max-age` directive states the maximum amount of time in seconds that fetched responses are allowed to be used again (from the time when a request is made) and because content on these URLs typically don't change, it is safe to cache them for really long periods.
16 | * Use a [cache-busting](https://www.keycdn.com/support/what-is-cache-busting) mechanism for versioning assets to ensure that the browser caches each version as a different URL. Example: `sncss-29d48c7.css` or `sncss.js?v=29d48c7` where “_29d48c7_” is an auto-generated number unique to every version of the file. Frameworks like [Shunter](https://github.com/springernature/shunter) use the filename version style which is preferred.
17 |
18 | ## General
19 |
20 | * If it is under your control, ensure the server provides an Entity Tag (`ETag`) header. The `ETag` header is an additional identifier for a specific version of a resource, typically comprised of the modified time and file size. (On older systems the ETag may also include an inode portion, but this is problematic.) The `Etag` header is especially useful to prevent simultaneous updates overwriting each other. If you use a CDN, it is likely this header will already be provided and properly configured. Learn more:
21 | * [MDN ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)
22 | * [Express options for 'ETag' setting](https://expressjs.com/en/api.html#etag.options.table)
23 | * You no longer need to use [`Expires` headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires) as it has been superseded by `Cache-Control` header with `max-age`, which is [supported by modern browsers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#Browser_compatibility).
24 |
25 | It’s important to note that there isn’t a one-size-fits-all approach to caching, so always decide a caching strategy based on your needs.
26 |
27 | ## Further resources
28 |
29 | * [Web Fundamentals: HTTP Caching](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching)
30 | * [HTTP Cache Headers: A Complete Guide](https://www.keycdn.com/blog/http-cache-headers)
31 |
--------------------------------------------------------------------------------
/performance/font-loading.md:
--------------------------------------------------------------------------------
1 | # Font loading
2 |
3 | - [When to use webfonts](#when-to-use-webfonts)
4 | - [Implementation](#implementation)
5 | - [Quick tips](#quick-tips)
6 | - [Understand the different user experiences in font loading: FOIT, FOUT and FOFT](#understand-the-different-user-experiences-in-font-loading-foit-fout-and-foft)
7 | - [Understand the different implementations available](#understand-the-different-implementations-available)
8 | - [WOFF and WOFF2 font formats](#woff-and-woff2-font-formats)
9 | - [font-display CSS](#font-display-css)
10 | - [Loading fonts with JavaScript](#loading-fonts-with-javascript)
11 | - [Preloading webfonts](#preloading-webfonts)
12 | - [Self host webfonts if possible](#self-host-webfonts-if-possible)
13 |
14 | ## When to use webfonts
15 |
16 | Webfonts allow us to bring emotion, personality and tone to our sites - which can make them more successful.
17 |
18 | However, the task of choosing a webfont and implementing it on your site should be approached cautiously. Webfonts have the potential to impact aspects of your sites such as accessibility and page speed. For example:
19 |
20 | - Certain webfonts may reduce the readability of the site, for example for people with dyslexia, or low vision.
21 | - Webfonts can negatively impact page performance (additional http requests and increased page weight) especially in markets of strategic importance for Springer Nature like China. This will in turn impact usage numbers.
22 |
23 | Our recommendation is that you prioritise a [system font](https://css-tricks.com/snippets/css/system-font-stack/) over a webfont. System fonts are extensively tested, and incur no performance penalty.
24 |
25 | If a webfont is needed then close collaboration between user experience, accessibility, and web performance specialists must be sought to ensure the choice is satisfactory from typographic, accessibility, and performance perspectives.
26 |
27 | As a Frontend Developer, it's your role to provide technical guidance and feedback, not to choose the font.
28 |
29 | ## Implementation
30 |
31 | We do not prescribe a particular implementation. Each team should determine which implementation is best suited for them. However, before selecting an implementation a team should be mindful of our working practices such as:
32 |
33 | - [Graded Browser Support](https://github.com/springernature/frontend-playbook/blob/main/practices/graded-browser-support.md)
34 | - Is the implementation supported by all "enhanced" browsers? If not, is there a good justification for selecting it anyway?
35 | - Does the implementation work in conjunction with the Cut The Mustard technique?
36 | - [Progressive Enhancement](https://github.com/springernature/frontend-playbook/blob/main/practices/progressive-enhancement.md)
37 | - This is not meant to force you to choose a non-js implementation, but rather for you to ensure you consider what will happen for users in varying circumstances from the beginning.
38 | - [Our Performance Goals](https://github.com/springernature/frontend-playbook/blob/main/performance/performance-checklist.md)
39 | - What impact will the implementation have on the page performance of your site?
40 |
41 | ## Quick tips
42 |
43 | Here are some quick suggestions for techniques that may prove useful:
44 |
45 | ### Understand the different user experiences in font loading: FOIT, FOUT and FOFT
46 |
47 | - FOIT means _flash of invisible text_. Text on the page is hidden while webfonts are loading, so users will see a page with images but no text. We only show the text when webfonts are loaded.
48 | - FOUT means _flash of unstyled text_. When webfonts are loading, we show users a system font. When the webfont gets loaded, we change the text back to the desired webfont.
49 | - FOFT means _flash of faux text_. Only load the roman character set initially and load the others later for less page render blocking. "Faux" refers to the fact the browser fakes italics and bold before those character sets have loaded.
50 |
51 | We believe that FOIT should be avoided as it is the worst experience for the user.
52 |
53 | ### Understand the different implementations available
54 |
55 | We highly recommend reading [Zach Leat's comprehensive guide](https://www.zachleat.com/web/comprehensive-webfonts/) to get a good understanding of the different techniques available. There is also a good [follow-up article](https://css-tricks.com/the-best-font-loading-strategies-and-how-to-execute-them/) that summarises Zach's findings.
56 |
57 | ### WOFF and WOFF2 font formats
58 |
59 | WOFF2 has a superior compression, and [is supported by all of our Enhanced browsers](https://caniuse.com/woff2), so there's no need to serve fonts in WOFF format.
60 |
61 | ### [font-display CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display)
62 |
63 | [`font-display`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) is useful and has the benefit of being a technique that does not require JavaScript and is easy and straight forward to implement.
64 |
65 | We recommend reading this [comprehensive analysis of font-display](https://calendar.perfplanet.com/2020/a-font-display-setting-for-slow-connections/) values when deciding which value is best for you.
66 |
67 | ### Loading fonts with JavaScript
68 |
69 | Consider using [FontFaceObserver](https://github.com/bramstein/fontfaceobserver) instead of the [CSS Font Loader API](https://drafts.csswg.org/css-font-loading/), as the latter does not have support for all our Enhanced browsers.
70 |
71 | ### Preloading webfonts
72 |
73 | If you have to load a font the conventional way using a `[MDN - Turning off form autocompletion](https://developer.mozilla.org/en-US/docs/Web/Security/Securing_your_site/Turning_off_form_autocompletion)
85 |
86 | As such, while you can disable autofill for sensitive fields (see MDN article above) browser vendors feel it is not a good idea overall.
87 |
88 | Secondly,
89 |
90 | > User agents should verify that all fields with the autocomplete attribute are visible within the viewport before automatically entering data.
91 | > — [HTML 5.3 W3C Working Group Note](https://www.w3.org/TR/2021/NOTE-html53-20210128/sec-forms.html#sec-autofill)
92 |
93 | So to be sure, *avoid enabling autocomplete for elements which may be visually-hidden*.
94 |
95 |
96 | ## Use the `sandbox` attribute for `iframe`s
97 |
98 | Even if you control the content of the `iframe`, do use the `sandbox` attribute if you can. This attribute restricts the functionality of the framed document [(_why "sandbox"?_)](https://en.wikipedia.org/wiki/Sandbox_(computer_security)).
99 |
100 | Note the default sandbox is very strict (e.g. no JavaScript, forms cannot be submitted) so tailor the value of the attribute to your use case. Mike West has written [a great article about `iframe sandbox`](https://www.html5rocks.com/en/tutorials/security/sandboxed-iframes/) and MDN has [a lovely reference article on `sandbox`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-sandbox).
101 |
102 | ## Use the `type` attribute for `object`s
103 |
104 | Either the [`data`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/data)
105 | or [`type`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/type)
106 | attribute for the [`object` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object)
107 | must be specified. You are encouraged to always ensure `type` is specified.
108 |
109 | The value should be a valid [MIME type](https://developer.mozilla.org/en-US/docs/Glossary/MIME_type), also know as a "content type".
110 |
111 | Embedded objects are generally not to be trusted -- security issues have arisen in the past from browsers being "tricked" into treating content as the wrong type, including [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) violations.
112 |
113 | For more information please see the [W3C HTML Living Standard](https://html.spec.whatwg.org/multipage/iframe-embed-object.html#the-object-element).
114 |
--------------------------------------------------------------------------------
/writing/README.md:
--------------------------------------------------------------------------------
1 | # Writing
2 |
3 | We write for a variety of audiences, and we must therefore take that into account whenever we write.
4 |
5 | * [House style](house-style.md)
6 | * [Inclusive language](inclusive-language.md)
7 | * [Social media](social-media.md)
8 |
9 | [Main table of contents](../README.md#table-of-contents)
10 |
--------------------------------------------------------------------------------
/writing/house-style.md:
--------------------------------------------------------------------------------
1 | # Language style guide
2 |
3 | * [Writing style](#writing-style)
4 | * [Tone of voice](#tone-of-voice)
5 | * [Plain English](#plain-english)
6 | * [Technical writing](#technical-writing)
7 | * [Frontend or front-end](#frontend-or-front-end)
8 |
9 | ## Writing style
10 |
11 | We don't enforce strict standards on writing style as we want you to use your own words to express your own personality. That said, we have three general sets of guidelines - tone of voice, plain English, and technical writing.
12 |
13 | ### Tone of voice
14 |
15 | For a general audience, you should write like a human. Be professional, but conversational - we want our contributors and readers to feel comfortable joining in at any time.
16 |
17 | Be thankful to contributors and those who log issues. They're giving up their time to make our playbook better. Make sure they know we're grateful to them.
18 |
19 | Maintain the same friendly and professional standards across the entire repository - in documentation, issues, pull requests, and comments.
20 |
21 | Always use [inclusive language](inclusive-language.md).
22 |
23 | ### Plain English
24 |
25 | Follow [Plain English guidelines](http://www.plainenglish.co.uk/how-to-write-in-plain-english.html) to help safeguard the accessibility of your written content. You might find tools like [Hemingway App](http://www.hemingwayapp.com/) helpful when editing. In particular:
26 |
27 | * Be concise
28 | * Check any sentences with more than 25 words to see if you can split them to make them clearer.
29 | * Ideally no more than 1-2 points per sentence.
30 | * Use contractions (e.g. "can't", "it's").
31 | * Go straight to the point.
32 | * Avoid unnecessary words (e.g. There is, It is, very, really, pretty, just, actually).
33 | * Be specific
34 | - Prefer the active voice to the passive voice[\[1\]][active-passive] (e.g. "NPM will install the dependencies" instead of "the dependencies will be installed").
35 | * Address the reader as "you" where possible.
36 | * Avoid referring to "things" or "stuff".
37 | * Be direct. Avoid metaphor, simile, and slang.
38 | * Be informative
39 | * Consider your audience. General information may not look the same as information aimed at a technical audience.
40 | * Be as precise as you can usefully be - consider linking to high quality external resources where relevant.
41 |
42 | ### Technical writing
43 |
44 | When expressing technical concepts, you'll need to use technical language. This may be complex, contain jargon, or seem formal. That's ok! Technical writing isn't for a general audience. Your priorities must be clarity, brevity, and accuracy. If you think your reader may need additional context to understand a concept, link out to external resources.
45 |
46 | All of the advice in the [plain English](#plain-english) section applies. Additionally:
47 |
48 | * Expand acronyms the first time you use them, and limit their use thereafter e.g. "Avoid the use of TLAs (Three Letter Acronyms)".
49 | * When defining technical requirements, you may use the keywords defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) for those requirement levels, e.g. "MUST", "SHOULD", "OPTIONAL", etc.
50 |
51 | ## Frontend or front-end
52 |
53 | Always use `frontend` regardless of the context. It's less confusing and error prone, and ensures consistency across all our documentation and portfolio of products.
54 |
55 | [active-passive]: https://oxfordediting.com/the-active-verb-form-makes-academic-writing-more-readable/
56 |
--------------------------------------------------------------------------------
/writing/inclusive-language.md:
--------------------------------------------------------------------------------
1 | # Inclusive language
2 |
3 | * [Non-discriminatory language](#non-discriminatory-language)
4 | * [Unacceptable language](#unacceptable-language)
5 | * [Language that excludes](#language-that-excludes)
6 | * [Gendered language](#gendered-language)
7 | * [Disability and accessibility](#disability-and-accessibility)
8 |
9 | ## Non-discriminatory language
10 |
11 | [Discrimination](https://en.wikipedia.org/wiki/Discrimination) is prohibited under law in the UK and many other countries.
12 |
13 | Language is our main form of communication and it plays a powerful role both in contributing to and in eliminating discrimination.
14 |
15 | Language influences thinking. For example, Hebrew uses gender markers, whereas Finnish doesn’t mark gender at all. A study done in the 1980s[\[1\]][wiley] found that kids who spoke Hebrew knew their own genders a year earlier than those who grew up speaking Finnish.
16 |
17 | Inclusive language is language that is free from words, phrases or tones that reflect prejudiced, stereotyped or discriminatory views of particular people or groups. It is also language that doesn't deliberately or inadvertently exclude people from being seen as part of a group[\[2\]][govau] .
18 |
19 | We're committed to using inclusive, non-discriminatory language in every written or verbal communication.
20 |
21 | ### Unacceptable language
22 |
23 | Inappropriate or unacceptable language highlights perceived or actual differences between people. The use of insensitive and inappropriate language can create a hostile environment for people who have protected characteristics, as outlined in the [Equality Act 2010](http://www.legislation.gov.uk/ukpga/2010/15/contents).
24 |
25 | Stereotyping means presuming a range of things about people based on their personal characteristics. These may include their appearance, apparent intelligence, personality or character, or their gender, sexual orientation, race, ethnicity, age, location, socioeconomic status or disability. We don't use language that reinforces stereotypes.
26 |
27 | ### Language that excludes
28 |
29 | Language matters. It remains a common practice in IT to use terminology like slave/master or blacklist/whitelist that reference slavery or segregation.
30 |
31 | There's always a better way to label the relationship between two entities. In the case of databases, choosing more descriptive terms like replica/primary, secondary/primary, follower/leader or standby/active instead of slave/master not only removes the reference to slavery, but also makes it easier to understand as it [avoids metaphor](https://github.com/springernature/frontend-playbook/blob/main/writing/house-style.md#plain-english).
32 |
33 | Similarly, in the case of blacklist/whitelist there are alternatives that better show their purpose to people not familiar with the terminology, like denylist/allowlist, blocklist/allowlist or block/permit. Choose a term that is appropriate and descriptive for your particular app or feature.
34 |
35 | ["Treat problematic terminology as technical debt. When you learn that you have it in your projects, make it a priority to remove it."](https://blog.carbonfive.com/problematic-terminology-in-open-source/)
36 |
37 | The [IETF has published a document (ietf.org)](https://tools.ietf.org/html/draft-knodel-terminology-01) that further describes the reasoning for avoiding this kind of language alongside further alternatives.
38 |
39 | ### Gendered language
40 |
41 | In most cases your writing will address the reader directly as "you", but if you do need to write about people in the abstract, avoid language that centers the male identity as the default. Try recasting your sentences as plural to make them more inclusive and concise. You can also use the [singular _they_](https://www.poynter.org/reporting-editing/2015/the-washington-post-will-allow-singular-they/) as per the Washington Post.
42 |
43 | Avoid "bro" language, even in verbal communication.
44 |
45 | We _don't_ say this:
46 | > Each student must complete his or her homework.
47 |
48 | > Server: Hello.
49 | >
50 | > Client: Hey _bro_, I have a message for you.
51 |
52 | > Hey guys!
53 |
54 | We say this:
55 | > All students must complete their homework
56 |
57 | > Server: Hello.
58 | >
59 | > Client: Hey server, I have a message for you.
60 |
61 | > Hey people!
62 | > Hey team!
63 |
64 | ### Disability and accessibility
65 |
66 | Using inclusive language is critical when writing about accessibility. Avoid references that dehumanise or 'other' people, or that cast them as helpless victims. Never use collective nouns like "the disabled" or "the blind" - these words are descriptors, not group labels.
67 |
68 | Use positive language that emphasises abilities rather than limitations. Consider whether you need to refer to a disability at all - for example, instead of writing about "users who are unable to use a mouse", perhaps you can be more precise with "keyboard users", or "users of alternative input devices".
69 |
70 | We _don't_ say this:
71 |
72 | > The disabled.
73 | > Dyslexics.
74 | > Susan is a victim of blindness.
75 | > People suffering from deafness.
76 | > Users who cannot see a screen.
77 |
78 | We say this:
79 |
80 | > Disabled people.
81 | > Dyslexic people.
82 | > Susan is blind.
83 | > Deaf people.
84 | > Screenreader users / blind users. [where relevant]
85 |
86 | The Special Interest Group on Accessible Computing (SIGACCESS) has published a [comprehensive guide to writing about disability](http://www.sigaccess.org/welcome-to-sigaccess/resources/accessible-writing-guide/) within the context of science and technology.
87 |
88 | You may also find the more general [gov.uk inclusive language guidance](https://www.gov.uk/government/publications/inclusive-communication/inclusive-language-words-to-use-and-avoid-when-writing-about-disability) helpful.
89 |
90 | [govau]: https://www.education.tas.gov.au/documentcentre/Documents/Guidelines-for-Inclusive-Language.pdf "Guidelines for Inclusive Language"
91 | [hemingway]: http://www.hemingwayapp.com/
92 | [wiley]: http://onlinelibrary.wiley.com/doi/10.1111/j.1467-1770.1982.tb00973.x/abstract "Language environment and gender identity attainment"
93 |
--------------------------------------------------------------------------------
/writing/social-media.md:
--------------------------------------------------------------------------------
1 | # Social media
2 |
3 | - [Cruft.io](#cruftio)
4 | - [Posting publicly](#posting-publicly)
5 |
6 | An important part of our work as developers is not only to create quality products, but also to raise awareness of accessibility, performance and progressive enhancement best practices. This includes promoting our work and our practices in open spaces like social media, conferences, talks and other events.
7 |
8 | For open-source projects, we aim to keep our projects up to date and fix any vulnerabilities in a timely fashion. Please see our [Open Source Support page](https://github.com/springernature/frontend-playbook/blob/main/practices/open-source-support.md) for details on how we do this.
9 |
10 | ## Cruft.io
11 |
12 | [Cruft.io](http://cruft.io) is a blog run by Springer Nature Technology. Anyone can post there and the instructions can be found in the [project's wiki (internal)](https://github.com/springernature/cruft/).
13 |
14 | ## Posting publicly
15 |
16 | Before publishing anything ensure that:
17 |
18 | * All the public communications follow our [language standards](house-style.md).
19 | * When reporting bugs or security issues, remember to use positive language instead of blaming.
20 | * Always use [inclusive language](inclusive-language.md).
21 |
22 | We do:
23 | > Released Shunter 1.2.3. Security upgrade of `nac` to 3.2.1 which addresses several vulns. https://github.com/springernature/shunter/blob/master/HISTORY.md#123-2017-03-08
24 |
25 | We _don't_ do:
26 | > Released Shunter 1.2.3. Fixes a vulnerability which was caused by a bug in `nac`, breaking our project. https://github.com/springernature/shunter/blob/master/HISTORY.md#123-2017-03-08
27 |
28 | * Always provide links where people can find further information if interested. E.g. a changelog for a software release, a blog article, a link to the frontend playbook, etc.
29 |
--------------------------------------------------------------------------------