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

Update guidance for "go to" #569

Open daobrien opened 3 months ago

daobrien commented 3 months ago

https://stylepedia.net/style/6.2/#n

Includes an entry for "navigate to".

This has been discussed more than once in the past and is now in direct conflict with IBM:

navigate verb Use only when a more direct verb, such as click, select, browse, or go to, is not applicable. Use only to provide direction to a location (for example, “Navigate to the directory that contains the files that you want to edit”).

"Go to" is much simpler language and "covers more bases" (sometimes there's no actual navigation involved) and is also suitable when directing readers to other web sites, etc. For everyday purposes, click, select, and browse are more restrictive. So far I haven't encountered a case where "go to" doesn't work, but many cases where one or more of the other options do not work.

https://github.com/RedHatTraining/vale-styles/issues/365 is in place to work on this.

julian-cable commented 2 months ago

I would indeed endorse a move away from "navigate to" as the preferred wording in favour of simpler wording such as "go to".

@sffrench @rclee33 Any comments welcomed.

rclee33 commented 2 months ago

I don't have a strong preference here - the proposed change sounds good to me!

sffrench commented 2 months ago

Sounds like a good change.

julian-cable commented 1 month ago

Some examples from David:

daobrien commented 1 month ago

As expected (and described at least in part in IBM), there's going to be some exceptions to this.

I don't have a "ruleset" at this point, but these sorts of things are showing up:

  1. Click the TabName tab. (Not "Go to...".)
  2. For something like "File > Save", or anything else where that's the end of the operation, I would still use "click". In these cases you're not actually going anywhere, but rather doing something specific.

I'll add more as I think of them.

julian-cable commented 1 month ago

I guess it might be a question of something along the following lines: Where you have used "click" or "select", continue to do so. Where you previously used "navigate to", now use "go to" instead.

rclee33 commented 3 weeks ago

I noticed another section where "navigate to" is documented in the Style Guide. I'm noting it here so that we can update this mention as well when the "go to" guidance is adopted.

Section 3.4.1.1 (under 3.4.1 https://stylepedia.net/style/6.2/#gui-elements-punctuation): "Navigating Through Multiple UI Options".

Screenshot 2024-06-05 at 11 13 38 AM