Fixing grammatical errors, spelling mistakes, inconsistent syntax, etc.

[koitsu]

Describe the issue

Been using AWS and AWS CLI for 11 years. Found many (and I do mean many: hundreds upon hundreds) of various documentation issues in examples, mainly:

• Grammar mistakes
• Spelling mistakes
• Syntactical mistakes -- extraneous spaces, extraneous blank lines, missing EOL at EOF, etc.
• CRLF vs. LF file format variances (should really be LF in Git)
• RST file syntax variances (sometimes this matters, such as extraneous blank lines ending up in rendered documentation)

I was going to take on the task of fixing all of these, and have already written some helper scripts (for myself, not for general use) to make this task easier, alongside leveraging aspell.

However, before I put bulk effort into this, I wanted to open an Issue and discuss with whoever oversees the documentation the following 2 items:

1. The sheer volume of these issues is huge. How would you like this work done, commit and branch-wise? One commit per category (see above bullet list)? Separate branches for each category? Doesn't matter?
2. Problems/concerns with sweeping commits (as I said: several hundred changes across hundreds of files)?
3. Is this worth taking on at all? Do you care?

Note: AI will NOT be used for this task. I am a human being vetting all of this by hand/eye.

I'm focused solely on v2 branch.

Thanks.

Links

Pretty much everything in awscli/examples.

[dominikhei]

I just checked the pre-commit config for this repo and noticed there aren’t any grammar or spelling checks currently in place. It might make sense to add them to help prevent similar issues in the future. If deemed helpful, I’d be happy to contribute by setting up those checks.

[koitsu]

Doninik, that would be great. Be aware, however, that most spell checkers (incl. aspell and hunspell) will report a very large number of unknown words on documentation due to the sheer number of AWS terms and examples used throughout.

As for me, I'm happy with doing the heavy lifting to clean up the existing stuff.

[dominikhei]

Doninik, that would be great. Be aware, however, that most spell checkers (incl. aspell and hunspell) will report a very large number of unknown words on documentation due to the sheer number of AWS terms and examples used throughout.

As for me, I'm happy with doing the heavy lifting to clean up the existing stuff.

If we add one of these spellcheckers we can define an exclusion file with words that are excluded by it, e.g EKS. The helpful thing is that it only checks files that are added with the current commit and thus one can simply add the flagged words in the staged files to the exclusion list.

[ashovlin]

@koitsu - thanks for opening this ahead of PR(s)!

Overall, we welcome improvements to the examples. If possible, try to split it up into PRs of a couple hundred lines each. Whether that's doing a subset of services (maybe alphabetically, like "A" through "G", "H" to etc.), or by the classes of issues you mentioned, we'll leave up to you.

1. Could you actually target the develop branch? We have a GitHub action that will copy changes to v2. Generally they're close enough that we can just cherry-pick.
2. Feel free to just target develop instead of a feature branch. Example changes tend to develop merge conflicts if someone else touches that service, so I'd rather merge as they're ready rather than wait.
3. fix(docs): correct typos found during code review #9842 from a few months ago is addressing some issues, let me see if we can get that merged first to avoid conflicts later.

We do some validation of RST in https://github.com/aws/aws-cli/blob/v2/tests/functional/docs/test_examples.py if you see any opportunities to improve there.

---

@dominikhei - I'd like to see a little more of that sketched out before committing to it. New pre-commit hooks or dependencies, even just for development, usually trigger more scrutiny and might require modifications in the internal build system.

[dominikhei]

@dominikhei - I'd like to see a little more of that sketched out before committing to it. New pre-commit hooks or dependencies, even just for development, usually trigger more scrutiny and might require modifications in the internal build system.

Definetly, I’ll test a few approaches and put together a draft proposal