Skip to content

Updated section about writing titles #492

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julian-cable merged 3 commits into from
Jun 23, 2023
Merged

Updated section about writing titles #492

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d5bde7a
Updated section about writing titles
julian-cable Jun 16, 2023
2c47bce
Reverted title ID
julian-cable Jun 21, 2023
d2f1165
Further edits
julian-cable Jun 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 42 additions & 3 deletions en-US/Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,52 @@
</para>
</formalpara>
<formalpara id="verbs-titles">
<title>Verbs in Titles</title>
<title>Writing Effective Titles</title>
<para>
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.
</para>
</formalpara>
<para>
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".
</para>
<para>
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".
</para>
<para>
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."
</para>
<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="c1"></colspec>
<colspec colname="c2"></colspec>
<thead>
<row>
<entry> Example </entry>
<entry> Improvement </entry>

</row>

</thead>
<tbody>
<row>
<entry> Understanding OpenShift Users and Groups </entry>
<entry> OpenShift Users and Groups </entry>

</row>
<row>
<entry> Introducing Cluster Updates </entry>
<entry> Cluster Updates </entry>

</row>

</tbody>

</tgroup>

</table>
<para>
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.
</para>
<para>
See the <citetitle>IBM Style Guide</citetitle> for more information.
Expand Down