Suggestion: add automated spell checker to Github workflow

The recent wave of typo fixes has brought into focus the problem of typos in the documentation. I would propose that an automated spell checker be added to the Github workflow. Such a checker would not catch all typos, but would handle those where the entered word was not in the dictionary. It would not catch atomic typos - typos where the entered word is a dictionary word. Nor would it handle the case where completely the wrong word has been used. Implementing an automated checker will reduce the amount of time developers spend on correcting typos in the documentation.

I had a go a few months ago at implementing such a system on one of my own Github repos, but did not get very far. It is, however, easy to run aspell on a local system with a suitable dictionary, and add words to a custom dictionary as you go along. It should therefore be fairly straightforward for someone with suitable skills to integrate spell checking into a Github workflow.

[lurch]

Yeah, it's something that we've discussed internally, but it's not yet bubbled up to the top of our priority list 😉 🔤

Instead of using aspell (which will find a bunch of false positives in the markup etc.), a much better option is codespell.

(sidenote: https://github.com/codespell-project/codespell/search?q=author%3Alurch&type=issues 🤣 )

Yeah, it's something that we've discussed internally, but it's not yet bubbled up to the top of our priority list 😉 🔤

Instead of using aspell (which will find a bunch of false positives in the markup etc.), a much better option is codespell.

(sidenote: https://github.com/codespell-project/codespell/search?q=author%3Alurch&type=issues 🤣 )

I ran aspell on some of the asciidoc files in this repo and the amount of false positives wasn't too bad. The problem with codespell is that unless a word has an entry in its dictionary, the typo will be ignored. (If I've understood correctly from the readme). Whereas what I want it to do is flag ever occurrence of a word that is not in an en_GB dictionary.

A full solution to the problem of typos would of course mean using more proof readers. And typos are just one class of error which a copy editor would be able to fix.

[aallan]

I'm (mildly) against automating spelling and grammar checks, my experience with doing it in the past hasn't been great. With technical documentation the false postive rate generally is just too high to make it useful. They tend to add to the editing workload rather than reduce it.

[aallan]

Wrong issue there on the assignments. 🙄

I'm (mildly) against automating spelling and grammar checks, my experience with doing it in the past hasn't been great. With technical documentation the false postive rate generally is just too high to make it useful. They tend to add to the editing workload rather than reduce it.

Presumably your preferred solution would be more proof readers then?

[aallan]

Presumably your preferred solution would be more proof readers then?

Yup, and we're also talking about that internally.

But I think the documentation needs serious restructuring before we waste time and effort on copy editing it. Basically, there's a lot of toolchain things we could do that I don't think we should do right now. Which isn't to say they're bad ideas.

[lurch]

I'm (mildly) against automating spelling and grammar checks, my experience with doing it in the past hasn't been great.

Yeah I'd never suggest automatically correcting spelling mistakes, only automatically reporting potential spelling mistakes (for a human to then manually fix up, should they choose to do so).

But I think the documentation needs serious restructuring before we waste time and effort on copy editing it.

I completely agree. And I like your suggestion that one third of the current documentation will be culled too. (Although some of the additions made recently during and post changeover are less concise than I would like).