ds-unslop

すっきり書く

下書きの段階から、明快に書きましょう。次に、以下の特徴がないか確認し、見つかったら書き直してください。意味と語調は保ちます。

取り除く特徴

単語

• 大げさな語彙：delve、crucial、pivotal、robust、seamless、leverage、utilize、showcase、underscore、tapestry、landscape、testament、vibrant、intricate。平易な語を使いましょう。
• 「serves as」「stands as」「boasts」。「is」や「has」と書きましょう。
• 抽象的な比喩表現の名詞：paradigm、north star、flywheel、substrate、bedrock。具体的なものの名前を書きましょう。
• 弱い動詞を補う副詞：「significantly improves」など。数値を示すか、より力強い動詞を使いましょう。

文

• 「Xだけでなく、Yも」。Yを述べましょう。
• 無理に3つ並べる表現。実際の数を使いましょう。
• 文末の「-ing」節：「ensuring reliability」「highlighting the need」など。削除するか、具体的な主張に書き換えましょう。
• 出典が曖昧な表現：「専門家によると」「多くの人が考えている」など。出典を明記するか、削除しましょう。
• 冗長な表現：「in order to」「it is important to note that」「due to the fact that」など。
• ヘッジ表現の重ねすぎ：「could potentially」など。限定表現を1つにするか、なくしましょう。
• 行為者が隠れる受動態。行為者を明記しましょう。
• 仕組みではなく感情を述べる表現。どのプロジェクトのドキュメントにもそのまま当てはまる文は削除しましょう。
• ありきたりな締めくくり：「未来は明るい」など。事実か、次の手順で締めくくりましょう。
• 圧縮しすぎた断片、矢印、記号による省略。冠詞と動詞を含む完全な文を書きましょう。

書式

• エムダッシュ。ピリオドかコンマを使いましょう。
• 文中のつなぎに使うコロン。リストの前ではコロンを使いましょう。
• あらゆる用語の太字表記や、「ラベル： ラベルを言い換えた本文」という箇条書き。
• 見出しのタイトルケース。文頭のみ大文字にしましょう。
• 装飾的な絵文字や曲線形の引用符。

チャットでの習慣

• 書き出しや締めくくりの決まり文句：「よい質問です」「もちろんです」「お役に立てば幸いです」「何かあればお知らせください」など。
• 反射的な同意。自分の判断を伝えましょう。

コードコメント

• 次の行の内容を説明するコメント、バナーコメント、コメントアウトしたコード。削除しましょう。
• コードだけでは説明できない理由を説明するコメントだけを残しましょう。

書き直しの手順

1. 読者が誰で、読み終えたあとに何をする、または何を理解する必要があるかを明確にします。
2. その目的に役立たない文をすべて削除します。
3. 同じものを指す類義語は1つに統一します。実際のファイル名、フラグ名、コマンド名を使います。
4. 2つの考えを含む文は分けます。文の長さに変化をつけましょう。
5. 条件を指示より前に置きます：「キャッシュをリセットするには、make clean を実行します。」
6. 「it」と「this」が何を指すのかを明確にします。
7. 曖昧な主張は数値、コマンド、具体例に置き換えます。
8. 特徴が残っていないか、もう一度読み直します。すべてのルールに従っていても、ぎこちない文は修正が必要です。

例

修正前：「この堅牢なツールは、ワークフローをシームレスに効率化する強力な手段として機能し、効率性を高めます。」

修正後：「sync.sh は変更されたファイルをサーバーに約2秒でコピーします。」