search

GSA / openacr

OpenACR is a digital native Accessibility Conformance Report (ACR). The initial development is based on Section 508 requirements. The main goal is to be able to compare the accessibility claims of digital products and services. A structured, self-validated, machine-readable documentation will provide for this.
https://gsa.github.io/openacr/
Other
82 stars 18 forks source link

Change capitalization throughout for consistency #222

Open danid123 opened 2 years ago

danid123 commented 2 years ago

Following 18f's guidelines:

Updates to be made:

Decision: Sentence case

mgifford commented 2 years ago

I am terrible at this. We need to look through and find more instances where it hasn't been done consistently.

mgifford commented 2 years ago

Ok, so looking at: https://gsa.github.io/openacr-editor/chapter/support_documentation_and_services

What do we do when we are referring to documents that use Title Case?

These are all based on Access Board documents:

https://www.access-board.gov/ict/

I think that if we're referring to an external document that is in Title Case we have to leave it that way. All of these apply.

bruce-usab commented 2 years ago

Just my own prejudices here. At USAB, our practice is to always capitalize EXCEPTION. Please let that data point inform how closely you wish to follow our model...

WRT title case versus sentence case, yes please be consistent.

18F might have there own style guide. From a search just now, it looks to me like USWDS v1 strongly advocated for sentence case over title case, but dropped that for v2. @danid123 do you happen to have a public-facing URL arguing for sentence case on headings?

From what I found at APA style guide there seems to be support for title case on headings.

It will be interesting to see if this comes up in the context of guidance which might follow WCAG3.

mgifford commented 2 years ago

Thanks for this @bruce-usab

With EXCEPTION you don't mean like here with WCAG: https://github.com/GSA/openacr/blob/main/catalog/data/wcag-2.0.yaml

But with sub-headings such as used here: https://www.access-board.gov/pvag/ch-v9/

I hadn't noticed that but it is good to know and keep track of.

Ultimately the GSA may need to decide on this, but I'm fine following existing examples in .gov sites where we can. Working towards consistency.

18F has this guide for content: https://content-guide.18f.gov/our-style/capitalization/

Most of the tone is about just not over-using Title Case as I read it.

Lots of interesting possibilities for WCAG3. Going to be an interesting transition.

danid123 commented 2 years ago

Title case is harder to read for long sentence-length titles because reader's eye does a lot of jumping up and down over the letters and cognitively the reader processes each word rather than the phrase. Sentence case is also perceived as friendlier which is helpful for a site with a lot of technical terms.

I couldn't find the specific line in the 18F guidelines but other civic tech resources collected some info on this topic.

Readability guidelines UK: https://readabilityguidelines.co.uk/grammar-points/capital-letters/

mgifford commented 2 years ago

Not that https://www.plainlanguage.gov/ is very consistent with this, but generally it seems they are going to Sentence case too.

But I still don't know what the right process is when you're referencing legislation that is in Title Case. That's the fuzzy zone I'm seeing.

bruce-usab commented 2 years ago

With EXCEPTION you don't mean like here ... But with sub-headings such as used here...

Yes, exactly. USAB uses All Caps (sometimes) as emphasis for consistency with stylistic choices from the pre-wordprocessor days. An argument could be made for those should be a strong em or even h. That was meant not as example that OpenACR should follow, but as a caution not to give too much weight for USAB preference for Title Case over Sentence Case.

Ultimately the GSA may need to decide on this, but I'm fine following existing examples in .gov sites where we can. Working towards consistency.

So very good!

18F has this guide for content

Okay, that is unambiguous, thanks for that!

melindaburgess commented 2 years ago

I also heartily agree that sentence case is a better choice, especially in government applications where there are a lot of acronyms and proper nouns that must be capitalized. Using sentence case for headings and titles makes it easier to distinguish what is a proper noun.

E.g. Using the OpenACR tool at the General Services Administration

mgifford commented 2 years ago

Are there more places where we should do this? Can we move this to done?