doc: use "previous"/"preceding" instead of "above" as modifier

[Trott]

Refs: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/above

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[nodejs-github-bot]

Review requested:

• @nodejs/modules

[GeoffreyBooth]

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.

[GeoffreyBooth]

Don't use to mean earlier.

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.

[Trott]

That link doesn’t explain why “above” is to be avoided.

Yeah, I opened an issue about that. MicrosoftDocs/microsoft-style-guide#177

My speculation from that link:

Is it because you don't want to make assumptions that people are reading things in a format that runs from top to bottom? For example, if someone is hearing it via a screen-reader, previous or preceding makes more sense than above?

[mcollina]

lgtm

[Trott]

I think they mean, avoid using “above” as a way to refer to some other section.

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."

[Trott]

@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:

Don’t use directional terms as the only clue to location. Left, right, up, down, above, and below aren’t very useful for people who use screen-reading software.

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.

[Trott]

Landed in ad2c22d