Skip to content

Update guidance about writing titles #483

@julian-cable

Description

@julian-cable

Apply to the style guide the updated guidance that Pat announced in a department meeting on 26 April 2023:

Use a title that represents the content.

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 "Troubleshooting" or "Installing".

Activities and subtasks that the student should perform can use an imperative verb for clarity. Imperative verbs are prescriptive, such as "Create" or "Delete".

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”, use a noun phrase. A noun phrase is descriptive and doesn't use a verb, for example "Installation Overview" or "The OpenShift Web Console."

When in doubt, trust your editor. Highlight the title and ask for assistance.

Metadata

Metadata

Assignees

Labels

P2Should address this soon.WIPWorking on it. Branch probably exists.enhancementWill improve the guide but is not a bug or blocker.

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions