コードを書くよりもマークダウンを書く方が私の最近の主務になりつつある。具体的にはガイドラインの類を書く機会が多いというだけではあるが、そんな中でキをつけて置きたいポイントを残しておく。いわば「ガイドラインのガイドライン」だ。

「ガイドラインのガイドライン」の目的

少数チーム・属人的でも問題があまりない状況から、人が増え、ガイドラインやルールを整え始めなければいけない時がある。どういうフォーマットやツールがいいか、などから考えはじめてしまうことはあるが、まず抑えておきたいポイントがいくつかある。

ガイドラインドキュメントは、それが使える・信用できるものでなければならない。この「ガイドラインのガイドライン」では、私が考える理想的なガイドラインドキュメントであるための必要なポイントを列挙する。すべてを満たさないといけないわけではないので、これからガイドラインを作り始める人にとって、一部でも参考になれば幸いである。

アクセス・更新しやすいか

ガイドラインドキュメントは運用されることが大前提。例えばIllustratorできっちり作られたものだと、デザイナー以外が触れないことが多い。またローカルディレクトリの奥深くに格納されたPDFデータなどはアンチパターンの代表で、アクセスしづらいし、もちろん更新もしづらくなる。

可能であればクラウドストレージでわかりやすく、アクセスしやすいところに編集データを置くか、Google スライドのような共同編集ができるものだとなお好ましい。Webサービスの場合、OS依存もほぼないので、特定の環境では更新できない、という問題も解消できる。

あとはお金の問題と、会社のルールとそれを決めるひとと相談だ。

更新日の記述があるか

ドキュメントは運用しないと腐る。そのドキュメントが生きているかどうかを知るためには更新・改訂日を残すのは必要だ。できれば更新した内容もログとして残すとなお好ましい。ドキュメント管理のサービスであれば、標準機能として更新日はログや差分が見られるものもある。

ファイルのタイムスタンプが更新されるときはあるが、それが内容が更新されたものかは分かりづらい。影響のありそうな改訂があったなら、それは明示的にドキュメントの表紙の日付を掲載し更新するか、あるいはドキュメントの1ページとして改訂履歴を用意できるのが好ましい。

目的が明記されているか

そのガイドラインが何を目的に、あるいは誰のために必要なのかを載せておきたい。暗黙的に、品質維持や標準化、チェックリストの役割を持つというようなイメージはあるかもしれないが、それらを明文化しよう。

これが無いとガイドラインに従う側はなぜ従うべきなのかはわからないし、あるいは対応できないケースが発生したときにどうするかの判断ができない。または運用上改訂をしなければいけないときにも、正しい方向、そのガイドラインの目的に沿わない形に変わっていくかもしれない。「なんでこのガイドラインをつくるのか」は初稿を起こすときにきっと考えているだろうから、それを文章にすればいい。

良い例・悪い例がわかりやすいか

良い・悪いの判断基準を持つものであれば、それがわかる例を明示したい。その場合、ただ例を載せるのではなく「なぜダメなのか」も添える。
もちろん可能なら図や写真でわかりやすいのが好ましい。

色だけに頼っていないか

前述の良い例・悪い例にもつながるが、色だけで情報を伝えるのは避けたい。例えば、悪い例を赤い色の枠線で囲むだけて表現するといったことだ。悪い例に関する説明であれば、その見出しやキャプションに「悪い例」や「Don't」のようなテキスト情報を添えたい。

またガイドラインのようなドキュメントは印刷を必要とすることがあり、理想を言えばモノクロ印刷であってもその内容がわからやすいのが好ましい。決して色を使うな、というわけではないので誤解しないでほしい。

使用している画像や文章の権利に問題はないか

UIガイドラインのようなものであれば、その例示に画像や文章が必要になることが多いはず。仮にそのドキュメントが社内だけで閲覧されるようなものであったとしても、インターネット上に転がっているものを無作為・無許可で素材として使うことは控えたほうがいい。

ライティングのルールが整っているか

「です・ます調」「ひらがなと漢字の使い分け」などWebサービス自体のライティングやUIラベリングのルールのように決めておくほうが好ましい。複数人が編集する前提であれば、こうした表記ルールは揺れやすいし、当初に1人で更新してたとしても揺れてしまうことがある。

表記ルールだけではなく、ガイドラインとしてのわかりやすさ・読みやすさを意識した記述テクニックなどがあればなお良い。回りくどさは避け、完結に記述する。

相談・問い合わせ先の記載はあるか

どう頑張ってもガイドラインの内容が万人にとって100%理解し、納得できるものにすることは難しい。あるいは、運用されていくと例外というものが生まれる。そうしたものにぶつかったとき、どうすればいいかを自己判断されるよりも、相談できる窓口があると良い。

これはクローズドで1対1でのコミュニケーションではなく、Slack用なグループチャットを活用できるならば、専用のチャンネルを設けてオープンに議論するのが良い。あるいは、ドキュメントツールにコメント機能があれば、そこにコメントできるようにするのも良いだろう。

完成されている必要はない

ガイドラインが求められるときは、大体「無いよりはマシ」であることが経験上は多い。ツールやフォーマットを考えるのに時間をかけすぎて、何も始まらず企画倒れになることも多いので、この記事であげたポイントは押さえつつ、アップデートされる前提でまず初めてみよう。項目ごとに決まていくことができたなら、すべてが完成できていなくても公開してしまおう。そしてフィードバックをもらって改善していくのが理想だ。

ドキュメントは腐る、ということを忘れない

「とりあえずはじめよう」といったものの、結局運用されないという現実もある。「そのドキュメントの内容は古いですね」というのが何度か聞こえたなら、もうそのドキュメントは腐っている。検索をして引っかかる腐ったドキュメントほどタチが悪いものもない。

そのときは割り切って削除してしまうか、非推奨であること・更新されないことをわかりやすく明記しよう。改めたドキュメントがあるならば、そちらに参照できるよう案内しよう。

腐ってしまったときには、なぜそうなったのかを振り返るようにしたい。運用体制に問題があったのか、そもそもガイドラインが必要とされていない・適切でなかったのか...ガイドラインを作ること自体を目的としないように気をつけよう。

フィードバックがあればコメント等に是非。