search

UKHO / docs

Documentation around digital development project, teams, behaviors and processes at the UKHO
MIT License
20 stars 11 forks source link

Workflow for Alex.js #115

Closed benbhall closed 3 years ago

benbhall commented 3 years ago

Following on from #109.

Alex.js still has fairly limited control but I don't think it is worth diving into other tooling like textlint, which will have it's own issues.

We can avoid warnings such as 'UK' by setting: "profanitySureness": 2.

Just need to decide on a workflow:

Deny list

Set only deny but risk being very limited in what we catch e.g.

 "deny": [
      "blacklist", 
      "blacklisted", 
      "blacklisting", 
      "whitelist",
      "whitelisting",
      "whitelisted",
      "whitespace"
      ]

Note those are rules, not words. See https://github.com/retextjs/retext-equality/blob/main/rules.md.

Allow list

We set only allow. Note deny and allow and mutually exclusive. This is my preference, although heavier upfront work on existing sources. This means all possible warnings that we might not consider are flagged. The author can either make the suggested changes or add to the allow list.

Allowed rules can be managed in different ways depending on situation:

Inline through comments: https://github.com/get-alex/alex#control e.g.

<!--alex disable dad-mom-->

In our package.json e.g.

 "allow": [
      "dad-mom"
      ]
benbhall commented 3 years ago

In favour of a allow list approach - I'd appreciate words like just, simple and easily being flagged in my writing to check if I am being condescending in the context.

It's a shame the guidance with the Alex warnings is not more detailed. The file in the retext-equality repo, for example, explains why just can be inconsiderate quite succinctly:

Not everything is as easy as you might think. And if it isn’t easy for the reader, it can hurt.