ドキュメントが欠かせない理由

欧米の企業とお仕事するときにいつも感心するのがドキュメントのボリュームと質。私も結構書く方だと思っていますが、それを容易に上回る情報量のドキュメントが共有されることがあります。ただ単に文字数が多いわけではなく、必要十分な情報が図なども交えて明文化されています。

エンジニアに限らず、デザイナーやプロダクトマネージャーもしっかりドキュメントを書く習慣が根付いているように見えます。恐らく下記の理由からしっかりドキュメントを書かざるを得ないのかもしれません。

  • 皆が同じ時間帯で仕事をしているわけではない
  • 場所も違うので「ちょっと話してすり合わせ」とはいかない
  • 英語が第一言語ではない人たちとコミュニケーションをしている
  • 文化も違うのでお互いがもつ『当たり前』が通じない

日本企業で日本語で通じ合える環境では馴染みがない状況です。ドキュメントを書かなくても、ちょっと話せば分かり合える場合もありますし、会議をして一気に決めることもできると思います。ドキュメントを書かなくてもなんとかなる環境が『甘えた情報共有』を許しているのかもしれません。

今だから高まるドキュメントを書くニーズ

コロナ禍になり、日本でも皆が同じ場所と時間を共にして仕事をするタイミングが減ってきました(少なくとも IT 系の現場では)。以前のように「話せば分かる」ができない機会が増えてきたと思います。チャットはその名の通り会話のためのツールですが、今の環境だと皆が同じタイミングでチャットツールを開いて会話できるとは限りません。

リモートワーク時代だからこそ非同期コミュニケーションを見直そうでも指摘しましたが、チャットは会話を追い続けていないと文脈を理解するのも極めて困難です。チャットは書き込みの敷居が低いですが、それによってストックされるべき情報も一緒に流れ去ることがあります。

非同期で情報共有するニーズが高まってきたのか、独自アプローチのドキュメントサービスや、現存サービスにドキュメント機能を追加するケースが増えています。

日本でも Notion  が注目されていますが、情報(知識)を蓄積する 場所をつくって「話せば分かる / 話さないと分からない」といった状況をなくすためかもしれません。

構造化からはじめる

新しいツールを使うのも良し。Word や Google Doc のような従来のツールを使うのも良いですが、肝心のドキュメントが書けない人は少なくありません。「スペースキーで見た目を整えるのはやめなさい」のような書籍が注目されているわりには、未だにリストを「・」で書く人は減っていないように見えます。

ここで言う「ドキュメントが書けない」とは、正しい日本語になっていないという意味ではありません。言葉足らずでも構造化さえしていれば、ある程度分かるものです。絵文字や装飾を凝る前に、下記の 4 点に注意するだけでもデザインドキュメントや議事録などの印象は大きく変わります。

要点を先に書く

書き手の思考の流れが淡々と書かれているだけで、結局これで何を伝えたいのか分からないドキュメントを目にすることがあります。逆ピラミッドというジャーナリストが使うテクニックを参考にして、要点を先頭に書き、その要点をサポートする情報(なぜそうなのか)を次に書くだけでもドキュメントの読み解きがしやすくなります。

見出しをつける

見出しがあれば長いドキュメントでもどこにどのような情報があるか把握しやすくなります。単にフォントサイズを上げて太文字にするのではなく、ツールで用意されているスタイリングを活用します。目次やページ内リンクなど、ツールによって見出しを設定することで付加価値がついてくるのでドキュメントの使い勝手が向上します。

1セクション1テーマ

せっかく見出しをつけても、その中に含まれる情報のテーマが複数あると受け手は何をどう理解すれば良いか分かり難くなります(そもそも見出しがつけ難いはずですが)。関連テーマであれば、見出しレベルを下げて関係性を示すと良いでしょう。

リンクをはる

ドキュメントに関係する情報にリンクを貼ることで、書かれている情報の文脈への理解が深まります。個人差はあるかもしれませんが、URL をベタ貼りにせずテキストリンクにしてあると、クリックした先に何があるか判断しやすくなります。

構造化して書くスキルを磨く

Markdown を書くことに慣れると構造化もしやすくなりますが、「###」や「>」といったコードのような見た目が文書に含まれるのを好まない人もいると思います。そんな方には、Markdown を自動的に整形してくれる Bear  がオススメです。コピー / 書き出しも Markdown 形式だけでなく、リッチテキストや HTML にも対応しているので、下書きを Bear で書いてからチームで使っているツールに貼り付けるといったワークフローも考えられます。

ドキュメントを書くスキルは、非同期でのコミュニケーションにおいて欠かせません。話すほうが楽という方はたくさんいると思いますが、ドキュメントはお互いの理解を深めることができますし、途中から参加した人も追いかけやすくなります。ツール選びに迷う前に、構造化したドキュメントを書く習慣をつけると良いでしょう。