Skip to content

Commit add567c

Browse files
WilHallWilHall
authored
Ensure that guides have consistent formatting (thoughtbot#618)
Fixes thoughtbot#617. This change ensures that all the guides have consistent Markdown formatting. It does not make any changes to the content. Formatting changes include: - Use GitHub style markdown - Make heading levels consistent and incremental - Make external links extracted instead of inline Additionally, I came across and fixed some editorial issues while reviewing all the guides: - Fixed/removed broken links - Fixed capitalization of technologies - Fixed spelling errors - Improved the link text for some external links - Replaced references to "Slack" with "Basecamp"
1 parent 24d95ee commit add567c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+1393
-1145
lines changed

‎CODE_OF_CONDUCT.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Code of Conduct
22

3-
By participating in this project, you agree to abide by the
4-
[thoughtbot code of conduct][tb-coc].
3+
By participating in this project, you agree to abide by the [thoughtbot code of
4+
conduct].
55

6-
[tb-coc]: https://thoughtbot.com/open-source-code-of-conduct
6+
[thoughtbot code of conduct]: https://thoughtbot.com/open-source-code-of-conduct

‎CONTRIBUTING.md

+9-9
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# Contributing
22

3-
We love contributions from everyone. By participating in this project, you
4-
agree to abide by the [thoughtbot code of conduct][tb-coc].
3+
We love contributions from everyone. By participating in this project, you agree
4+
to abide by the [thoughtbot Code Of Conduct].
55

66
We expect everyone to follow the code of conduct anywhere in thoughtbot's
77
project codebases, issue trackers, chatrooms, and mailing lists.
88

9-
[tb-coc]: https://thoughtbot.com/open-source-code-of-conduct
9+
[thoughtbot code of conduct]: https://thoughtbot.com/open-source-code-of-conduct
1010

1111
## Getting Feedback
1212

@@ -16,13 +16,13 @@ least a week to get feedback from everyone.
1616

1717
## Content
1818

19-
Decisions about which libraries to use should live in template projects such
20-
as [Suspenders].
19+
Decisions about which libraries to use should live in template projects such as
20+
[Suspenders].
2121

22-
[Suspenders]: https://github.com/thoughtbot/suspenders
22+
[suspenders]: https://github.com/thoughtbot/suspenders
2323

2424
### The Anatomy of a Guide
2525

26-
Whether you're creating a new guide or adding to an existing one, you can reference [the template guide] if you're unsure where to put things.
27-
28-
[the template guide]: /_template/
26+
Whether you're creating a new guide or adding to an existing one, you can
27+
reference [the template guide](/_template/) if you're unsure where to put
28+
things.

‎README.md

+11-10
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)
44

5-
Guides for working together, getting things done, programming well, and programming in style.
5+
Guides for working together, getting things done, programming well, and
6+
programming in style.
67

78
## High level guidelines
89

@@ -58,7 +59,7 @@ Guides for working together, getting things done, programming well, and programm
5859
- [Objective-C](/objective-c/)
5960
- [Python](/python/)
6061
- [Ruby](/ruby/)
61-
- [SASS](/sass/)
62+
- [Sass](/sass/)
6263
- [Scala](/scala/)
6364
- [Shell](/shell/)
6465
- [Swift](/swift/)
@@ -84,24 +85,24 @@ Guides for working together, getting things done, programming well, and programm
8485

8586
## Contributing
8687

87-
Please read the [contribution guidelines] before submitting a pull request.
88+
Please read the [contribution guidelines](/CONTRIBUTING.md) before submitting a
89+
pull request.
8890

89-
In particular: **if you have commit access, please don't merge changes without waiting a week for everybody to leave
90-
feedback**.
91-
92-
[contribution guidelines]: /CONTRIBUTING.md
91+
In particular: **if you have commit access, please don't merge changes without
92+
waiting a week for everybody to leave feedback**.
9393

9494
## Credits
9595

96-
Thank you, [contributors](https://github.com/thoughtbot/guides/graphs/contributors)!
96+
Thank you,
97+
[contributors](https://github.com/thoughtbot/guides/graphs/contributors)!
9798

9899
![thoughtbot](http://presskit.thoughtbot.com/images/thoughtbot-logo-for-readmes.svg)
99100

100101
Guides is maintained by [thoughtbot, inc](https://thoughtbot.com).
101102

102103
## License
103104

104-
Guides is © 2020 thoughtbot, inc. It is distributed under the
105-
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/3.0/).
105+
Guides is © 2020 thoughtbot, inc. It is distributed under the [Creative Commons
106+
Attribution License](http://creativecommons.org/licenses/by/3.0/).
106107

107108
The names and logos for thoughtbot are trademarks of thoughtbot, inc.

‎_template/README.md

+12-8
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,28 @@
11
# Template
22

3-
In a sentence or two, describe what this guide is about. A guide can be about a programming language or framework, a design or development tool, or an entirely non-technical topic.
3+
In a sentence or two, describe what this guide is about. A guide can be about a
4+
programming language or framework, a design or development tool, or an entirely
5+
non-technical topic.
46

57
## Best Practices
68

7-
In this section (or as many sections as you need) convey the best practices around the topic of the guide.
9+
In this section (or as many sections as you need) convey the best practices
10+
around the topic of the guide.
811

912
This typically takes one of three forms:
1013

11-
1. A section or sections with lists of specific [guidelines]
14+
1. A section or sections with lists of specific
15+
[guidelines](/README.md#a-note-on-the-language)
1216
2. Primarily textual sections
1317
3. A combination of both
1418

15-
[guidelines]: /README.md#a-note-on-the-language
16-
1719
## How to...
1820

19-
This section, if applicable, should index a list of "How-to" guides for this guide's topic. These should be stored relative to this `README.md` file in a folder named `how-to`.
21+
This section, if applicable, should index a list of "How-to" guides for this
22+
guide's topic. These should be stored relative to this `README.md` file in a
23+
folder named `how-to`.
2024

2125
Here are some examples:
2226

23-
- [Do something](./how-to/do-something.md)
24-
- [Do something else](./how-to/do-something-else.md)
27+
- [Do something](./how-to/do-something.md)
28+
- [Do something else](./how-to/do-something-else.md)

‎_template/how-to/do-something-else.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
## How to Do Something Else
22

3-
This is an example how-to guide. Write anything you want here!
3+
This is an example how-to guide. Write anything you want here!

‎_template/how-to/do-something.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
## How to Do Something
22

3-
This is an example how-to guide. Write anything you want here!
3+
This is an example how-to guide. Write anything you want here!

‎accessibility/README.md

+97-70
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,123 @@
1-
Accessibility
2-
=============
1+
# Accessibility
32

43
A guide for auditing and maintaining accessible web sites and apps.
54

6-
Basics
7-
------
5+
## Basics
86

9-
thoughtbot strives for AA level [Web Content Accessibility Guideline (WCAG)][wcag] compliance. Perform one or more of these checks to ensure your work is accessible.
7+
thoughtbot strives for AA level [Web Content Accessibility Guideline (WCAG)]
8+
compliance. Perform one or more of these checks to ensure your work is
9+
accessible.
1010

1111
### Automation
1212

1313
Automated checks can catch a lot of common issues before they reach production.
1414

15-
* Use tools such as [WAVE][wave] or [axe's browser extensions][axe-web] to run audits on your local build
16-
* Use a CI/CD solution such as [AccessLint][accesslint] or [axe][axe]
15+
- Use tools such as [WAVE] or [axe's browser extensions] to run audits on your
16+
local build
17+
- Use a CI/CD solution such as [AccessLint] or [axe]
1718

1819
### Usability
1920

20-
Manual usability testing ensures things [work as intended][manual-testing].
21+
[Manual usability testing] ensures things work as intended.
2122

22-
* Test your local build using a screen reader such as [VoiceOver][voiceover] or [NVDA][nvda]
23-
* Use tools such as [Accessibility Insights][accessibility-insights] to catch
24-
issues that cannot be found using automated checks
25-
* Hire assistive technology users to user test your product
23+
- Test your local build using a screen reader such as [VoiceOver] or [NVDA]
24+
- Use tools such as [Accessibility Insights] to catch issues that cannot be
25+
found using automated checks
26+
- Hire assistive technology users to user test your product
2627

27-
Quick checks
28-
------------
28+
## Quick checks
2929

3030
### Design
3131

32-
* Ensure all content's foreground color values meet the [minimum contrast ratio][color-contrast] for the background color they are placed over
33-
* Ensure all interactive content has distinct hover and focus states to help indicate interactivity
34-
* Ensure color is not the only way to determine meaning
35-
* Ensure interactive components use common UI affordances where applicable, to help users understand how they can be operated
36-
* Prefer icons and glyphs that don't rely on specialized knowledge to understand their meaning, unless being used in a domain-specific context
37-
* Prefer language that is [simple and direct][readability]
38-
* Ensure form inputs have labels that are visible in every state
39-
* Ensure link and button text is descriptive and distinct
40-
* Prefer content that is broken into logical sections, with headings that explain the content that follows
41-
* Prefer text sizing that is set to 16px or larger
42-
* Ensure animation does not auto-play, can be paused, and avoids [vestibular and seizure triggers][vestibular-seizure]
43-
* Ensure video content has captions
44-
* Prefer larger interactive target sizes, with some space between grouped interactive controls
45-
46-
### Development
47-
48-
* Ensure semantic markup is used to describe content
49-
* Ensure content does not disappear off the screen when zoomed
50-
* Ensure that interactive content can be tabbed to and activated using the keyboard, and that the tab order matches reading order
51-
* Ensure that heading elements are used, and that heading levels are placed in a logical order
52-
* Ensure that landmarks are used to describe the overall layout of the page or view
53-
* Ensure that alternative descriptions for image content are concise, descriptive, and use punctuation (`alt` attributes for images, `title` elements for SVGs)
54-
* Ensure labels are programmatically associated with their inputs
55-
* Prefer implementing a method to allow users to skip sections of repeated content
56-
* Ensure each page or view has a unique title that describes the content it contains
57-
* The `title` attribute is only used to describe `iframe` element contents
58-
* Ensure that links are used to navigate to other locations and buttons are used to trigger actions
59-
* Ensure that focus is trapped inside of modal interactions
60-
* Ensure `fieldset` and `legend` elements are used to group related inputs and label them
61-
* Ensure form feedback messaging is programmatically associated with the relevant inputs
62-
63-
Full audit
64-
----------
65-
66-
When at all possible, use the guidelines in the basics and quick check sections to attempt to address accessibility in a proactive way.
67-
68-
If a thorough analysis needs to be performed, use the following workflow to perform a comprehensive accessibility audit that checks against most WCAG criterion:
69-
70-
1. Create a copy of [the Accessibility Audit Template][accessibility-audit-template] spreadsheet in Google Drive
71-
1. Break apart the site or app to be audited into discrete user flow sections, ordered by importance
72-
1. Add yourself as the section lead on the audit template, document the relevant URL and date, and set a status
73-
1. For each user flow, identify each component that enables the user flow to function
74-
1. For each component, check against the test criteria for each row, and then assign it one of four ratings:
75-
* **N/A**: This test does not apply to this component
76-
* **Pass**: This component meets this test's criteria
77-
* **Moderate**: This component does not meet this test's criteria, but can worked around
78-
* **Critical**: This component does not meet this test's criteria, and cannot be worked around
32+
- Ensure all content's foreground color values meet the [minimum contrast ratio]
33+
for the background color they are placed over
34+
- Ensure all interactive content has distinct hover and focus states to help
35+
indicate interactivity
36+
- Ensure color is not the only way to determine meaning
37+
- Ensure interactive components use common UI affordances where applicable, to
38+
help users understand how they can be operated
39+
- Prefer icons and glyphs that don't rely on specialized knowledge to understand
40+
their meaning, unless being used in a domain-specific context
41+
- Prefer language that is [simple and direct]
42+
- Ensure form inputs have labels that are visible in every state
43+
- Ensure link and button text is descriptive and distinct
44+
- Prefer content that is broken into logical sections, with headings that
45+
explain the content that follows
46+
- Prefer text sizing that is set to 16px or larger
47+
- Ensure animation does not auto-play, can be paused, and avoids [vestibular and
48+
seizure triggers]
49+
- Ensure video content has captions
50+
- Prefer larger interactive target sizes, with some space between grouped
51+
interactive controls
52+
53+
### Development
54+
55+
- Ensure semantic markup is used to describe content
56+
- Ensure content does not disappear off the screen when zoomed
57+
- Ensure that interactive content can be tabbed to and activated using the
58+
keyboard, and that the tab order matches reading order
59+
- Ensure that heading elements are used, and that heading levels are placed in a
60+
logical order
61+
- Ensure that landmarks are used to describe the overall layout of the page or
62+
view
63+
- Ensure that alternative descriptions for image content are concise,
64+
descriptive, and use punctuation (`alt` attributes for images, `title`
65+
elements for SVGs)
66+
- Ensure labels are programmatically associated with their inputs
67+
- Prefer implementing a method to allow users to skip sections of repeated
68+
content
69+
- Ensure each page or view has a unique title that describes the content it
70+
contains
71+
- The `title` attribute is only used to describe `iframe` element contents
72+
- Ensure that links are used to navigate to other locations and buttons are used
73+
to trigger actions
74+
- Ensure that focus is trapped inside of modal interactions
75+
- Ensure `fieldset` and `legend` elements are used to group related inputs and
76+
label them
77+
- Ensure form feedback messaging is programmatically associated with the
78+
relevant inputs
79+
80+
## Full audit
81+
82+
When at all possible, use the guidelines in the basics and quick check sections
83+
to attempt to address accessibility in a proactive way.
84+
85+
If a thorough analysis needs to be performed, use the following workflow to
86+
perform a comprehensive accessibility audit that checks against most WCAG
87+
criterion:
88+
89+
1. Create a copy of the [Accessibility Audit Template] spreadsheet in Google
90+
Drive
91+
1. Break apart the site or app to be audited into discrete user flow sections,
92+
ordered by importance
93+
1. Add yourself as the section lead on the audit template, document the relevant
94+
URL and date, and set a status
95+
1. For each user flow, identify each component that enables the user flow to
96+
function
97+
1. For each component, check against the test criteria for each row, and then
98+
assign it one of four ratings:
99+
- **N/A**: This test does not apply to this component
100+
- **Pass**: This component meets this test's criteria
101+
- **Moderate**: This component does not meet this test's criteria, but can
102+
worked around
103+
- **Critical**: This component does not meet this test's criteria, and cannot
104+
be worked around
79105
1. Once a component is completed, update its status
80106
1. Continue until all user flows have been audited
81107

82-
Use the Notes sheet to leave per-cell comments when necessary, referencing them with a link. The next steps for an audit are handled on a per-project basis.
108+
Use the Notes sheet to leave per-cell comments when necessary, referencing them
109+
with a link. The next steps for an audit are handled on a per-project basis.
83110

84-
[accessibility-audit-template]: https://docs.google.com/spreadsheets/d/1Ys-0U5BY-Ct_phy7gk9XJmn4nBTMFTh08aTQ6U1kB_4/edit?usp=sharing
111+
[accessibility audit template]: https://docs.google.com/spreadsheets/d/1Ys-0U5BY-Ct_phy7gk9XJmn4nBTMFTh08aTQ6U1kB_4/edit?usp=sharing
85112
[accesslint]: https://github.com/marketplace/accesslint
86113
[axe]: https://www.deque.com/axe/axe-for-web/integrations/
87-
[axe-web]: https://www.deque.com/axe/axe-for-web/
88-
[color-contrast]: https://webaim.org/resources/linkcontrastchecker/
89-
[manual-testing]: https://www.smashingmagazine.com/2018/09/importance-manual-accessibility-testing/
114+
[axe's browser extensions]: https://www.deque.com/axe/axe-for-web/
115+
[minimum contrast ratio]: https://webaim.org/resources/linkcontrastchecker/
116+
[manual usability testing]: https://www.smashingmagazine.com/2018/09/importance-manual-accessibility-testing/
90117
[nvda]: https://a11yproject.com/posts/getting-started-with-nvda/
91-
[accessibility-insights]: https://accessibilityinsights.io
92-
[readability]: https://datayze.com/readability-analyzer.php
93-
[vestibular-seizure]: https://alistapart.com/article/designing-safer-web-animation-for-motion-sensitivity/
118+
[accessibility insights]: https://accessibilityinsights.io
119+
[simple and direct]: https://datayze.com/readability-analyzer.php
120+
[vestibular and seizure triggers]: https://alistapart.com/article/designing-safer-web-animation-for-motion-sensitivity/
94121
[voiceover]: https://a11yproject.com/posts/getting-started-with-voiceover/
95122
[wave]: https://wave.webaim.org/extension/
96-
[wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/
123+
[web content accessibility guideline (wcag)]: https://www.w3.org/WAI/standards-guidelines/wcag/

‎android/README.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,6 @@
22

33
In addition to [java](/java/) best practices:
44

5-
- Properties of views should be alphabetized, with the exception of `id`, `layout_width`, and `layout_height` which
6-
should be placed first in that order.
5+
- Properties of views should be alphabetized, with the exception of `id`,
6+
`layout_width`, and `layout_height` which should be placed first in that
7+
order.

‎angular/README.md

+9-10
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,14 @@
1-
Angular
2-
-------
1+
# Angular
32

4-
* [Avoid manual dependency annotations][annotations]. Disable mangling or use a
5-
[pre-processor][ngannotate] for annotations.
6-
* Prefer `factory` to `service`. If you desire a singleton, wrap the singleton
3+
- [Avoid manual dependency annotations]. Disable mangling or use a pre-processor
4+
such as [ngannotate] for annotations.
5+
- Prefer `factory` to `service`. If you desire a singleton, wrap the singleton
76
class in a factory function and return a new instance of that class from the
87
factory.
9-
* Prefer the `translate` directive to the `translate` filter for [performance
10-
reasons][angular-translate].
11-
* Don't use the `jQuery` or `$` global. Access jQuery via `angular.element`.
8+
- Prefer the `translate` directive to the `translate` filter for [performance
9+
reasons].
10+
- Don't use the `jQuery` or `$` global. Access jQuery via `angular.element`.
1211

13-
[annotations]: http://robots.thoughtbot.com/avoid-angularjs-dependency-annotation-with-rails
12+
[avoid manual dependency annotations]: http://robots.thoughtbot.com/avoid-angularjs-dependency-annotation-with-rails
1413
[ngannotate]: https://github.com/kikonen/ngannotate-rails
15-
[angular-translate]: https://github.com/angular-translate/angular-translate/wiki/Getting-Started#using-translate-directive
14+
[performance reasons]: https://github.com/angular-translate/angular-translate/wiki/Getting-Started#using-translate-directive

‎bash/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## Bash
1+
# Bash
22

33
In addition to [shell](/shell/) best practices:
44

0 commit comments

Comments
 (0)