From d5bde7a81e1446c28de420b7b9abdef9a5ef6d61 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 16 Jun 2023 17:18:12 +0100 Subject: [PATCH 1/3] Updated section about writing titles --- en-US/Design.xml | 47 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 4648444..fd2e183 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -46,14 +46,53 @@ Do not use terminating periods. - - 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 gerund form of a verb is a good way to title larger chunks of content such as chapters and sections. Gerunds end in "ing", such as "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 student 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 + + + + + + + +
+ + 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. From 2c47bce6425c3aa60149902ee9f85f26579ed07d Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 21 Jun 2023 15:42:38 +0100 Subject: [PATCH 2/3] Reverted title ID --- en-US/Design.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index fd2e183..5d502eb 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -46,7 +46,7 @@ Do not use terminating periods. - + Writing Effective Titles Use a title that represents the content. From d2f1165901e5446831db8e66a99d9750dad41db3 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 22 Jun 2023 14:48:45 +0100 Subject: [PATCH 3/3] Further edits --- en-US/Design.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 5d502eb..8d9963c 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -53,13 +53,13 @@ - Typically, the gerund form of a verb is a good way to title larger chunks of content such as chapters and sections. Gerunds end in "ing", such as "Creating Branches". Choose a verb that refers to specific actions that users take, such as "Configuring", "Creating", "Installing", and "Merging". + 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 student 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”. + 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." + 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." @@ -92,7 +92,7 @@
- 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. + 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.