Fix various typos in docs/ subdirectory

[luzpaz]

Fixes to english docs/*.adoc documentation files
Follow-up to #2548

[SebKuzminsky]

Thanks for these fixes.

Not as part of this PR, but in general, maybe it would be good to have a script that checks if there are any spelling errors. We could run it in the Buildbot and the GitHub Actions and reject PRs that introduce spelling errors...

[luzpaz]

Thanks for these fixes.

You're welcome. Thank you for all you work on this project.

Not as part of this PR, but in general, maybe it would be good to have a script that checks if there are any spelling errors. We could run it in the Buildbot and the GitHub Actions and reject PRs that introduce spelling errors...

Indeed, check out https://github.com/codespell-project/actions-codespell

[c-morley]

I disagree with automatic blocking of prs because of spelling mistakes.
An automatic report would be fine though.

[SebKuzminsky]

I disagree with automatic blocking of prs because of spelling mistakes.
An automatic report would be fine though.

How do you propose these reports would be generated and communicated?

We currently have implemented a policy (aligned with your opinion and aligned against mine) that failures in our automatic build tests do not prevent us from merging a PR.

Does this mean you're ok with adding a spelling check to our GitHub Actions and to the Buildbot? The result of the spelling check would show up along with the results of all the existing tests we have; in the red X indicating failure or the green checkmark indicating success. But just like now, a developer could choose to ignore the "red X" failure and merge the problematic PR anyway.

[hansu]

I am ok with adding a spelling check to our GitHub Actions. Yes we can ignore a failure on that action if a PR need to be merged quickly, but on the long run it would be better to add an exception for that reported spelling error (or just correct it if possible).

[petterreinholdtsen]

[Sebastian Kuzminsky]

"vise" is correct here, this patch is wrong.

This seem related to the choice of American English over my personal preference British English. There is also a proposal to use the Chicago style in the documentation, ref <URL: #2062 > and <URL: #1844 >.

…

-- Happy hacking Petter Reinholdtsen

[luzpaz]

Just a note regarding the codespell as a github action:
It does give some false positives, so spellcheck failure auto-blocked PRs are not ideal because of this.

[c-morley]

I disagree with automatic blocking of prs because of spelling mistakes.
An automatic report would be fine though.

How do you propose these reports would be generated and communicated?

We currently have implemented a policy (aligned with your opinion and aligned against mine) that failures in our automatic build tests do not prevent us from merging a PR.

Does this mean you're ok with adding a spelling check to our GitHub Actions and to the Buildbot? The result of the spelling check would show up along with the results of all the existing tests we have; in the red X indicating failure or the green checkmark indicating success. But just like now, a developer could choose to ignore the "red X" failure and merge the problematic PR anyway.

I am saying I see the utility of spell checking. I don't know the best way to offer that information to the developer.
But I am also saying that having slightly misspelled docs is better then no docs.

[c-morley]

I disagree with automatic blocking of prs because of spelling mistakes.
An automatic report would be fine though.

How do you propose these reports would be generated and communicated?

We currently have implemented a policy (aligned with your opinion and aligned against mine) that failures in our automatic build tests do not prevent us from merging a PR.

Does this mean you're ok with adding a spelling check to our GitHub Actions and to the Buildbot? The result of the spelling check would show up along with the results of all the existing tests we have; in the red X indicating failure or the green checkmark indicating success. But just like now, a developer could choose to ignore the "red X" failure and merge the problematic PR anyway.

I am saying I see the utility of spell checking. I don't know the best way to offer that information to the developer.
But I am also saying that having slightly misspelled docs is better then no docs.

[petterreinholdtsen]

[c-morley]

But I am also saying that having slightly misspelled docs is better then no docs.

I thought the issue at hand here were to give documentation writers quick feedback on any misspellings, to get the fixed before merging new doc into release branches, similar to giving quick feedback when code changes break on some platform, to have the issue fixed before it affect other people. In what scenario will the alternative be no docs? -- Happy hacking Petter Reinholdtsen

[c-morley]

Because if the process has too much 'friction' ie the PRs sit for too long before being approved it discourages people investing time into linuxcnc.

Spelling mistakes while annoying are not going to break limuxcnc'

[c-morley]

Sorry -butter fingers on phone..

...not going to break linuxcnc's use.
If the developer doesn't fix the spelling mistakes then we don't get the docs (so no docs) or the developer doesn't even bother with the PR because the process is painful ( so no docs) or the docs are held up for months(?) Till someone fixes the dozen spelling mistakes (so no docs for a long time)

Particularly talking of new or one time developer PRs.

[petterreinholdtsen]

So if I understand correctly, the underlying problem is that the feedback period is long, and almost no-one respond to pull requests to the author in a timely manner. I would guess the solution would be to focus more on providing feedback to pull requests quicker, not reduce the quality control.

…

-- Happy hacking Petter Reinholdtsen

[hansu]

I think we should give it a try and add it as a GitHub action.
If one doesn't want to deal with spelling erros, he can ignore that failed check and merge it anyways. The downside is only that from this merge all builds will fail at first sight (if not looked at the specific steps) until the spelling errors are fixed.

[c-morley]

So if I understand correctly, the underlying problem is that the feedback period is long, and almost no-one respond to pull requests to the author in a timely manner. I would guess the solution would be to focus more on providing feedback to pull requests quicker, not reduce the quality control.
…
-- Happy hacking Petter Reinholdtsen

Sure that would help a lot- how do you propose we do that?
We already tried forcing reviews of every PR and that didn't seem to work out very well.

Having a policy of only including 'perfect code' is a great idea in theory.
But in practice we just don;t have enough people in the right places to so that.

A policy of trying to stop code that breaks linuxcnc builds/functions but allows some minor stuff like miss spelling is just a practical fact of running a small nobody-gets-paid volunteer project.

Hopefully this check could be set up to announce spelling mistakes as warnings not errors as not to dilute the required attention error messages mean.