こんにちは、スタイルガイドについて四六時中考えていても飽きない山本です。
Googleスタイルガイドの優れたところ
まずそもそもですが、「スタイルガイド」と聞くとコーディングのお作法のことかと思う人も多いかもしれません。実際に”style guide”でググるとC++やPythonのスタイルガイドが先に出てきます。
ですが今日扱うのはドキュメンテーションのスタイルガイドです。
テクニカルサポートとして日々働く自分から見て筋が良さそうと思った点を列挙してみます。
- 二人称（You）を使う
- 能動態で書く
このあたりは人間にも読みやすく、機械翻訳もしやすい言葉遣いになりやすくていいと思います。
日本語でどうするのか問題
ただ、日本語は「あなたは」とユーザーを指しにくい問題があります。そもそも主語を入れると不自然な文になったり、敬語にしにくくなったりしてしまうからです。
その場合もGoogleスタイルガイドに沿って地の文と操作手順を分けるテクニックを使ってみましょう。
例えば製品ガイドを想定すると次のようになります。
▶︎あるページを特定のユーザーが閲覧できない場合には次の手順をお試しください。
- 管理者としてログインする
- ページの権限設定に共有対象のユーザーを追加する
- …
こんな感じです。地の文は敬体で書いて、手順は平易な文で記述します。ポイントは、手順の最初に前提となる操作の主体（例の場合は「管理者」）を記載することです。
こうすることで、暗黙の前提を排除できて分かりやすいドキュメントを作成できます。
それでは。
広告
