canonical/open-documentation-academy

Charmed Ceph: Replace gerunds with imperatives

オープン

#278 opened on 2025/08/12

 (14 件のコメント) (0 件のリアクション) (1 人の担当者)Python (99 件のフォーク)auto 404
good first issuesize 1workshop

Repository metrics

Stars
 (119 個のスター)
PR merge metrics
 (PR metrics pending)

説明

[! IMPORTANT] Notice that this task contains a workshop label; this means that it has been created for the live DjangoCon/Ubucon 2025 Open Documentation Academy workshop to assist community members make their first documentation contribution. Please, do not work on this task unless it is assigned to you.

Background

In the Charmed Ceph how-to guides, the use of gerund instead of imperative violates a our style guide. It also creates an inconsistent voice in both the index and text. The use of imperative delivers a clear command and helps users understand they need to perform an action. The use of gerund can hint at a description, and can lead to confusion, as users might think an explanation will follow. This reduces the precision of the documentation and reduces the functional quality. Since the information is not presented in the most actionable way, it can be harder to engage with and feel less intuitive to the user, which could decrease the deep quality.

For example, “Replace OSD disks” rather than “Replacing OSD disks” is clearer that it is a step to be followed rather than an explanation, and, therefore, more actionable.

Task

Replace all gerunds in the index with imperatives, e.g. change “Installing Ceph” to “Install Ceph”.

Resources

Thank you in advance for your contribution!

コントリビューターガイド