よりよいコンテンツの書き方
日本語スタイルについて
現時点では（2024年11月現在）、ハンドブックは日本語で記述するものとします。将来国際化が必要となることも想定されます。
日本語の記述については、「JTF 日本語標準スタイルガイド」に従って記述しなければなりません。
https://www.jtf.jp/pdf/jtf_style_guide.pdf
例
| ○ | ✗ | |
|---|---|---|
| 実行しましょう。 | 実行すること。 | 本文は敬体を使用すること。 |
| 報告してください。 | 報告して下さい。 | ひらがなと漢字の使い分けの誤り。 |
| コンピューター | コンピュータ | カタカナ語の語尾の長音は省略しない。 |
| カー・ナビゲーション・システム | カーナビゲーションシステム | 長いカタカナ複合語は全角中黒または半角スペースで区切る。 |
要求レベルの表現の統一について
あいまいさを回避するために、以下の表現を用いて要求レベルを明確にすることを推奨します。これは RFC2119 の 「Key words for use in RFCs to Indicate Requirement Levels」をベースとしています。
MUST
以下の表現が用いられている文章は、絶対に守られるべき条件を意味しています。守られなかった場合、新しい別の問題が生まれる可能性が非常に高いことを意味しています。
- しなければなりません。
- 必ず 〜 してください。
MUST NOT
以下の表現は MUST の逆で、絶対に行われてはならない禁止事項であることを意味しています。MUST と同様に、禁止事項を破ることで高い可能性でなんらかの問題が生じることを意味しています。
- してはいけません。
- 絶対に 〜 しないでください。
SHOULD
以下の表現は、MUST ほどの強制力はありませんが、守ることを推奨することを意味しています。守らなかったことで必ずしも問題が生じることがないかもしれませんが、他のチームメンバーによる手助けが必要になるかもしれません。
- 〜 してください。
- 〜 することを推奨します。
SHOULD NOT
以下の表現は、MUST NOT ほどの強制力はありませんが、避けるべきであることを意味しています。SHOULD と同様に守らなかったことで必ずしも問題が生じることがないかもしれませんが、他のチームメンバーによる手助けが必要になるかもしれません。
- 〜 しないでください。
- 〜 しないことを推奨します。
解説
たとえば、「経費精算はX日までにしなければなりません。」と記載があれば、必ずX日までに経費精算をすることがルールとして明確に定められているということを意味しています。
一方で、「◯◯はX日までに提出してください」という記述であれば、「必ずとまでは言わないがX日までに提出することが推奨されている」ということを意味しています。この場合、必須ではないからと言って、「遅れたことがまったく問題がない」ということを保証しているわけではないことに注意してください。
ルールを厳密に運用することにはコストがかかります。そのコストを削減するために「〜してください」というあいまいな表現を用いることが一般的に多くありますが、あまりにもひどく守られない場合は「必ず」という表現が付け加えられることがあります。この場合、あなただけではなく他のチームメンバーもコストが増えうることを十分に理解してください。