docs: Simplify lists maintenance and fix language #527
Conversation
.github/CONTRIBUTING.md
Outdated
| @@ -105,7 +105,7 @@ You can use [this PR](https://github.com/antonbabenko/pre-commit-terraform/pull/ | |||
| ### Before write code | |||
|
|
|||
| 1. Try to figure out future hook usage. | |||
| 2. Confirm the concept with [Anton Babenko](https://github.com/antonbabenko). | |||
| 1. Confirm the concept with [Anton Babenko](https://github.com/antonbabenko). | |||
There was a problem hiding this comment.
Any sensible reason to use this type of how numbered lists are rendered? If I wanted to edit markdown file as plain text in terminal editor, I'd expect it to use natural numbering rather than what markdown viewer would take as a numbered list. We even don't need to bother about human mistakes: markdown renders into numbered list even lists with random numbering and the only requirement is that first item in the list should be "number one with trailing dot".
There was a problem hiding this comment.
I got tired of changing numbers every time something is added or rearranged somewhere
and in general, I don’t care what the number is when you read the source code, because as a docs you will still watch the rendered md
So better use 1. to be consistent, than have 1. 5. 2. 3. 7. list
There was a problem hiding this comment.
I got tired of changing numbers every time something is added or rearranged somewhere
It's a bit odd your IDE can't handle lists renumbering automatically. Poor you, though it is not the reason for odd lists with the same number for all items 🤷🏻
I don’t care what the number is when you read the source code, because as a docs you will still watch the rendered md
Well, I might be missing something, though what I do for living is not just reading docs, though writing code too.
So better use 1. to be consistent, than have 1. 5. 2. 3. 7. list
Given your attitude and use case, I'd suggest you just use unordered lists rather than neglect common sense 😺
There was a problem hiding this comment.
An unordered list can't be mentioned when you point someone to README. Now I start thinking about adding anchors to each point to be able to point folks exactly to what they need to read, and then we can change many lists to unordered. But I'm not sure it's worth it. In any case, if it will be done - it is out of the scope of this PR
Spelling/language fixes look good to me. Though changes to lists — do not. Sorry 🤷🏻 |
|
This PR is included in version 1.80.0 🎉 |
Description of your changes
Quick improvements, which were done during work on #526, but were separated to this PR as not related changes