0

Are there defined rules anywhere concerning whether a UI element type (e.g. drop-down list) comes before or after its name (e.g. Install)? A few examples:

  1. the drop-down list Install vs. the Install drop-down list

  2. the table MATNR vs. the MATNR table

  3. the option Copy existing content to target table vs. the Copy existing content to target table option

  4. the options Copy content, Save content and Delete content vs. the Copy content, Save content and Delete content options

The same would apply to words like “parameter”, “window”, “tab” and “chapter”.

Does the length of the name affect this rule? E.g. Something like “if more than four words, write the name before the UI element”. (example 3)

Or whether multiple UI elements are described as opposed to just one? (example 4)

Or whether the UI element type functions as a noun or an adjective?

  • When the name follows the noun, we tend to drop the article: The records are found in [] table CUST. The records are stored in the CUST table. – Tᴚoɯɐuo Mar 13 '18 at 15:48
1

In your example, I would always use the name before the thing. I'm sure if you read enough technical manuals you will notice this.

Install dropdown

since otherwise it would be

the dropdown for Install

this way the name is the adjective for the object.

the MATR table
the Copy existing content to target table option
the Copy content, Save content and Delete content options

although in the last example

the options for Copying, Saving and Deleting content.

might be preferable, depending on usage.

As with all technical writing, it is important to be consistent since these are instructions and not a story.

  • Thanks Peter. In #4, those are the exact button names in the GUI, so I have to keep them as is. So a long description like "Copy existing content to target table" still functions as an adjective? Even if it were to contain 10+ words? I know that 10+ words should be avoided, but I often can't change what is written in the software. – Laurence Mar 13 '18 at 8:59
  • Unfortunate that you can't change the wording since "Copy To Table" would suffice (obviously, you can only copy existing content and the table would be the target). For the documentation to be as clear as possible, it's usually best to quote labels and buttons exactly as they appear. – Peter Mar 13 '18 at 16:01

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.