doc: use "previous"/"preceding" instead of "above" as modifier #34877
Conversation
|
Review requested:
|
nodejs-github-bot
added
doc
|
That link doesn’t explain why “above” is to be avoided. “Previous”/“preceding” aren’t necessarily better, as to a casual reader a phrase like “the previous example” could be thought to mean an example in an earlier section, not the example in this section just prior to this sentence. |
I think they mean, avoid using “above” as a way to refer to some other section. As in, “the previous section,” not “the above section,” because the documentation may or may not all be on the same page (sections might be broken up onto separate pages/URLs). When referring to things within the same section, I think above/below are fine. |
Yeah, I opened an issue about that. MicrosoftDocs/microsoft-style-guide#177 My speculation from that link:
|
They're explicit that they mean don't use it as a modifier at all. I believe they meant what they wrote: "Don't use as an adjective preceding a noun (the above section) or following a noun (the code above). Use a link, or use previous, preceding, or earlier." |
|
@GeoffreyBooth For what it's worth, it looks like my suspicion that this is about accessibility is correct. From https://docs.microsoft.com/en-us/style-guide/accessibility/writing-all-abilities:
I don't know that our API docs are useful to people using screen-readers and similar technologies, but I guess I also don't know that they aren't useful to them. And ideally, it should be useful to them. But I also don't want to make the docs worse for the common use case. Hopefully, "preceding" works. But if not, I have some other ideas too. And if all else fails, I'll go with your suggestion or else restore "above" and not worry about that one instance for now. |
Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/above PR-URL: nodejs#34877 Reviewed-By: Jan Krems <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Anto Aravinth <[email protected]> Reviewed-By: Franziska Hinkelmann <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
|
Landed in ad2c22d |
Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/above PR-URL: #34877 Reviewed-By: Jan Krems <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Anto Aravinth <[email protected]> Reviewed-By: Franziska Hinkelmann <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/above PR-URL: #34877 Reviewed-By: Jan Krems <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Anto Aravinth <[email protected]> Reviewed-By: Franziska Hinkelmann <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/above PR-URL: #34877 Reviewed-By: Jan Krems <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Anto Aravinth <[email protected]> Reviewed-By: Franziska Hinkelmann <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/above
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passes