StyleGuides / WritingStyleGuide

The official Red Hat guide to writing clear, concise, and consistent technical documentation.
Creative Commons Attribution Share Alike 4.0 International
71 stars 19 forks source link

Improve example table for homonyms #568

Open daobrien opened 3 months ago

daobrien commented 3 months ago

https://stylepedia.net/style/6.2/#avoiding-ambiguities Table 4.7.

The following is given as an example: Tab through the dialog box. Set the tab. Move the tab on the ruler. How to show or hide tabs. Select the tab.

tbh it's not clear if that's supposed to be a single example or multiple examples of how "tab" can be used, or misused. ("Tab" as a verb is not valid in our vocab.)

The "improvement" in the second column suffers from the same issue.

A lot of the language also contradicts the guide's own advice. E.g., we don't write "Select the View tab."

I also don't think the second row is a good example of homonymity.