態のスタイル

Ansible ライティングスタイルの特長は、自然に一緒に流れる短い文です。文法構造は混在させます。文の主題を変化させます。読者に直接話しかけます。質問します。読者が短い文章のペースに順応したら、長い文章を書いてください。

• 実際のユーザーが話すように記述します。
• …ただし、他言語に適切に翻訳できない可能性のある俗語や口語表現は避けるようにしてください。
• 小さなことばで大きなことを説明します。
• 直接的な表現を使用してください。読み手が実行する必要がある内容を正確に指示します。
• 誠実に表現します。
• 短い文章は自信を示しています。
• 文法規則は、何を説明しているかを読者が理解している場合に限り組み込まれることが意図されています。
• 読みやすく、理解を深めるために、音節が少ない単語を選んでください。
• コピーは、聴衆に対するスピーチではなく、1 対 1 の対話と考えてください。直接話しかけている人を無視するのはより困難です。
• 可能な場合は、タスク指向の文章 (ユーザーによる作業を指示する項目) は、動作を示す用語で開始します。たとえば、「Find software…」、「Contact support…」、「Install the media…」などです。

能動態

可能な限り、受動態 (「”Linuxconf can be started by typing…」) ではなく、能動態 (「Start Linuxconf by typing…」) を使用します。能動態の方がより生き生きとした、注意を引き付ける文章になります。 また、未来時制 (または「will」の使用) は可能な限り使用しないでください。たとえば、未来時制 (「The screen will display…」) と能動態 (「The screen displays」) では、ニュアンスが異なります。ほとんどの場合、読者は、そのシステムの使用前または使用後ではなく、使用中にドキュメントを参照する点に注意してください。