WritingRule

リファレンスマニュアルを記述するときのルールについて

Rubyリファレンスマニュアル記述規約

• 一文を短くする。

• 一段落で言うことは一つだけにする。

• 結論から書く。

• 主語と動詞の次元を合わせる。

• コンテキストに依存しないこと。 ReFe などでそのメソッドのエントリだけが表示された場合も 意味が通じるようにこころがける。

• 語尾は「です、ます」調に統一する。

• 常用漢字は意識しなくてよい。必要なら使う。

• アラビア数字とアルファベットは半角文字で書く

• 半角文字のまわりには半角空白を入れる (例：「第 1 引数 pattern は……」)

• 「〜ものです」はできるだけ避ける。

• 「〜することができます」よりは「〜できます」のほうがいい。

• 括弧はできるだけ減らす。

• 括弧を使うときはできるだけ短くする。括弧の中身が 1 行を越えるようなら括弧から出す。

• 括弧のネストなど論外。

• 参照以外に脚注を使わない。

• 多段の脚注など論外。

• 箇条書きを濫用しない。

• リンクに頼りすぎないこと。 「こうなっている理由については [ruby-list:13445] を見てください」 のような文章を書くべきではない。 リンク先に何が書いてあるのか文章で説明するべき。 文章で説明する価値がないと思うなら、この文自体を消す。

• Ruby のコード例は、説明した各パターンをできるだけ網羅するように書く。

• Ruby のコード例を書くときは、警告が出ないコードを書く。 ただし、警告を出すことが目的の場合を除く。

• Ruby のコード例を書くときは、コードが動作することを確認する。 実際に動かしたコードをコピペするとよい。

• 見出しを積極的に使う。 技術文書を書くことに慣れていない人は見出しをあまり使わない傾向があるので、 最初はできるだけ見出しを入れていったほうがよい。

• 見出しをすべて取っても意味が通じるようにする。 具体的には、見出しの内容を本文の冒頭でもう一度書くようにする。

• 見出しレベルを深くしすぎない。

最終奥技

• 悩んだら ML で聞く