diff --git a/en-US/Design.xml b/en-US/Design.xml index 4648444..8d9963c 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -47,13 +47,52 @@ - Verbs in Titles + Writing Effective Titles - Usually, you start a title with the gerund form of a verb, which ends with "-ing", for example "Creating Branches". Choose a verb that refers to specific actions that users take, such as "Configuring", "Creating", "Installing", and "Merging". + Use a title that represents the content. - The gerund verb form is not always required. For example, avoid verbs such as "Describing", "Introducing", and "Understanding", because they add little value. Instead, use a more specific verb or omit the verb. For example, instead of "Describing Initial Git Configuration", you can use "Initial Git Configuration". + Typically, the "ing" form of a verb is a good way to title larger chunks of content such as chapters and sections, for example "Creating Branches". Choose a verb that refers to specific actions that users take, such as "Configuring", "Creating", "Installing", and "Merging". + + + Activities and subtasks that the user should perform can alternatively use an imperative verb for clarity. Imperative verbs are prescriptive, such as "Create" or "Delete". Example: "Assess the Health of an OpenShift Cluster". + + + In some cases, a verb might not be appropriate because the content is purely informational. Instead of using a vague verb like "Understanding", "Describing", "Introducing", or "Exploring", either use a more specific verb, or use a noun phrase instead of a verb. A noun phrase is descriptive and omits a verb, for example "Installation Overview" or "The OpenShift Web Console." + + + + + + + + + Example + Improvement + + + + + + + Understanding OpenShift Users and Groups + OpenShift Users and Groups + + + + Introducing Cluster Updates + Cluster Updates + + + + + + + +
+ + In training content, avoid using a verb such as "Discussing" or "Demonstrating" in objectives for students. Such verbs might refer instead to what the instructor or the course content covers, or to a student group activity in class. See the IBM Style Guide for more information.