Remove pompous, archaic and complicated language

[garethrees]

Like many services, WhatDoTheyKnow started small catering to a niche audience. That audience was well educated and of a certain background similar to its creators. Over the last 15 years we’ve successfully broadened the appeal of FOI to a massively more diverse audience. We’ve done that through making the service increasingly accessible.

There are still many remnants of the public school-esq language, or language that while well intentioned is difficult to understand. Here are a few examples:

• Extraneous material
• House rules
• “Caveat emptor!”
• “How, why and by whom requests are categorised is not straightforward”

Lots of these have been improved over the years, but some still exist across the application UI, the help pages, and our internal templates.

There are many readability tests and applications that generate a score that can help us identify the least accessible pieces. While making all our content perfect is likely too much of an ask, we should aim to improve the worst performing sections.

A rough order of operations will be:

1. Grade the content using a combination of automation and personal judgement
2. Identify a reasonable target to get all content to, based on the amount of work (for example, improve content rated F to a C grade, or if that feels huge, maybe it’s getting all F to E, and all E to D to help push things forward.
3. Rewrite the content that we’ve identified as the worst such that it hits our target grade.

While we’re not against using more specific and precise terms, we should only do so where it’s necessary. Where we do use more unfamiliar terms – pseudonym, vexatious, defamatory, etc – we should try to link to the glossary or use something like an <abbr> tag that expands on their meaning.

There are some related issues in https://github.com/mysociety/whatdotheyknow-theme/milestone/13 which we might be able to tackle within the scope of this issue.

====================
Here are examples we have already addressed

• “Careful scrutiny of the legislation, however, shows that you are at liberty to write articles about the information, summarise it, or quote parts of it”
  https://www.whatdotheyknow.com/help/requesting#reuse
  https://web.archive.org/web/20190330155818/https://www.whatdotheyknow.com/help/requesting#reuse

[mdeuk]

This is definitely something that is needed.

Another one to add, may well be the classification screen itself - more than a few users seem to be mystified by the options. Perhaps we could back it off to a help page, which clearly outlines what each option means / does?

[ajparsons]

I very agree with this. A lot of the general principles here are covered in the mySociety style guide, but not consistently applied to older content.

A few notes:

• I've wondered (and experimented with this on CAPE) with moving help content into markdown to help with long term maintenance and easier tweaks with less technical knowledge. Also more clearly separates content for automated readability checks.
• For democracy work I had a think about the voice we wanted, which might be a useful thing to frame in a few paragraphs who you think the site is for, and why we're explaining things in the first place.

This bit on jargon has been backported back into the full style guide, but I think we do want to stamp out latin:

When it comes to obscure or industry-specific words and phrases, a lot of standard professional language may be impenetrable to outsiders. If you are italicising Latin terms, consider what the plain English term would be, and whether it is clearer for most readers. “Per capita” and “per person” mean exactly the same thing and one is much clearer. Reframing into English may also raise questions that further improve clarity (did you mean “per resident”, “per citizen”, “per worker”, etc). If possible, avoid Latin (also Greek, Medieval French, etc).

This carries over a bit to FOI, in that there's a double problem of "here is something complicated" and "We do not think it is good it is complicated":

Explanations of Parliament (both ours and in general) generally approach it as an education project, where the public need to be educated about how Parliamentary democracy works. But the failure of Parliament to make its own processes legible to citizens is part of wider attitudes to exclude, rather than welcome, all citizens to understand and participate in British democracy. What we need to do to make it accessible isn't 'explaining something complicated' but attacking that system of exclusion.

[garethrees]

Thanks both! ❤️

• Another one to add, may well be the classification screen itself
• moving help content into markdown

To keep things manageable the scope of this issue is rewriting text, not any substantial change to interfaces or backends. Both of these things are very much on our radar and worth us considering in future though.

[WilliamWDTK]

I agree that this is a good idea.

We might want to outline a more detailed process. For example:

1. Are we copying it all into a Google Doc for editing?
2. Which pages/parts and when?
3. Should we do a spreadsheet?
4. Exactly how we're assessing content.

There was nothing minuted about this, but the note in @HelenWDTK's call round-up was:

Removing archaic language: Archaic language, with its ostentatious grandeur and antiquated phraseology, has surreptitiously seeped into the very bones of our application. As such, it strikes us that the hour is nigh when we must attend to this matter with the gravest urgency. The aim is to make the language we use more accessible and easier to understand. We thought it would be good to start with the language in alaveteli and the help pages, before moving on to things like the email templates we use.

[HelenWDTK]

Readability scoring: https://docs.google.com/spreadsheets/d/11mO4Gyf8lsVYWynPaEbvivzIjC2ujIuU61jyjXzTnPc/edit?usp=sharing

Generated by a python script that removed <%= tagged things, and then used BeautifulSoup4 to pass the content to textstat.

[HelenWDTK]

The script also asked for improvement suggestions, which are here:
https://drive.google.com/drive/folders/1ClJzjRlQJe8NZUCBRnw49pls0TFmIyJq?usp=drive_link

[HelenWDTK]

The house rules page (5 red, 5 yellow) seems like it should be a priority, given their importance in reducing misuse.

[HelenWDTK]

This has come onto my radar through user support. Am noting it here as it needs a rewrite to make sense:

https://www.whatdotheyknow.com/help/unhappy#refer-to-ico