🕶️

チームの誰でも一定品質のドキュメントを書けるフォーマットをつくってみた話

2023/12/27に公開

team

doc

idea

はじめに

開発やサービスインまでにスピード感を求められがちな昨今ですが、
そんな中でどうしてもコストカットされがちなドキュメントを書くことの大切さについて
改めて書いてみようと思います。

ドキュメントとは

今回書く「ドキュメント」は主に以下のようなものを対象とします。

クライアント・上長向け提案・合意資料
要件・設計書類
ナレッジ共有資料

昔はきちんとドキュメント化できていたのか？

10〜15年くらい前に比べて、
最近はIT業界で求められるスピード感は明らかに高まっていると思います。
では、そこまでの要求がまだ顕在化してなかった昔は
きちんとドキュメントできていたのでしょうか？
いいえ。私はそうは思いません。
右も左もわからない未経験新卒の頃から
SES案件にて様々なクライアントやSierの方々と一緒に仕事をさせて頂く機会がありましたが、
しっかりしたドキュメント化を行なっているところもあれば、
全然そんなことはないところもありました。
そういう文化を醸成できているかどうかの違いなのだと思っています。

ドキュメント有無による違い

人を迎え入れるために

まず、何らかの案件に参画する際に、
充実した導入資料の有無はキャッチアップに大きく影響します。
ドキュメントが充実している現場では、
基本的な導入作業やドメイン知識はドキュメントから得ることが出来て、
業務へのコミットが可能になるまでの時間は早かったように思います。
逆にドキュメントが充実していない現場では、
有識者に聞かねばその先に進めない・何をすべきかがわからないようなケースが
多く発生してしまいます。
聞く人が１人だけであればまだ良いですが、
熟知している部分が人によって違ったりすると複数人にお伺いすることもしばしばです。
これは聞く方もそうですが、聞かれる方も稼働を割くことになるため
コストが多重にかかってきますし、お互いにストレスを感じることにもなると思います。
また、参画者のモチベーション低下にも繋がり、案件からの早期離脱の可能性もでてきます。
私の限られた経験でもそう言ったケースを目にすることがありました。
わからないことはどんどん人に聞いて、
必要なことを能動的に吸収していくようなマインドを持つように努力すればいいのでは？
という意見もあると思いますし、それも間違いだとは思いません。
ただ、全員が全員そういうマインドの持ち主ではないことも確かです。
もしかしたら、うまくキャッチアップできた後は
とても素晴らしいパフォーマンスを発揮してくれる人もいるかもしれません。
人手不足が叫ばれて久しいIT業界で
一定のケアさえできていれば排他しなくて済むケースを
ケアせずそのままにしておくことはもったいないと思います。

認識の乖離をなくすために

これはずっと言われ続けていることで、当たり前と言えば当たり前なのですが
クライアントや組織上長との合意事項や
要件・設計についてをドキュメント化することも大切です。
ドキュメント化していれば、言った言わないの水掛け論や
仕様の認識齟齬によるバグの混入と
それによる手戻りで発生する余計なコストを防止することができます。
採択するプロジェクト推進・開発手法（ウォーターフォール、アジャイル）による差も
基本的にないと考えています。
どこまで詳細にドキュメント化すれば推進する上で充足しているか？
という点である程度の差が生まれることはあるかもしれません。

でもドキュメント書くのは苦手

ドキュメントを書くのは大切と思っている方でも、
ドキュメントを書くのが苦手という人も結構いると思います。
私の参画している直近のプロジェクトでは、
どうすれば個々の苦手意識を低減化できるかをチームで検討する試みを行いました。
その活動の中で分かってきた一つが、
「個々の詳細内容は書けるけど、相手に伝えるための全体のストーリーを構成するのが苦手」
だということでした。
各人でメモ書き程度のものは結構残していても、
それを体系化して管理できてない状態が多かったように思います。
その解決策としてドキュメント作成における要素についてさらにチームで検討して、
ドキュメント作成のフォーマットを用意しました。

ドキュメントフォーマット

以下のフォーマットに当てはめてドキュメントを作成することで、
ドキュメント内部のストーリー（起承転結）を
ある程度画一的に構成することを目的としています。
各構成要素はすべてがMUSTではなく、ドキュメントの属性によって取捨選択して利用します。

No	構成要素（見出し）	記載内容	備考
1	タイトル	ドキュメントのテーマを表現する。キャッチコピー的なもの。	ファイル名と合わせる
2	概要	1〜2文程度で資料の概要を表現する。タイトルをもう少し詳細化するイメージ	タイトルと概要でそのドキュメントの大枠を把握してもらう
3	目的	何の目的で作成するドキュメントなのかを表現する
4	スコープ（本書の位置付け）	ドキュメントで取り扱う範囲を表現する以下のようなものを適宜記載する。・期間・システム全体における該当箇所・運用箇所	プロジェクト全体の中でどの部分について言及しているかを分かるようにする。全体構成図の中で該当部分を赤枠で囲って表現などするとわかりやすい
5	背景・課題（AS-IS・TO-BE）	このドキュメントの目的がなぜ必要なのか等、ドキュメント作成に至った経緯について表現する
6	提案・検討案	目的を達成するための具体的な案を可能な限り詳細に記載する
7	達成事項（ゴール）	何ができればこのドキュメントの役目を果たしたと言えるのかを表現する。以下のようなものを適宜記載する。・要件の合意・運用の合意・課題に対する解決方針の合意
8	懸念事項	達成する上でのリスクや不明点などを表現する
9	依頼事項	相手側に対応頂きたいことを簡潔に表現する
10	その他	上記に当てはまらないが、ドキュメント固有で見出し単位で切り出す必要のあるものは適宜見出しとして取り扱う

視認性・可読性の向上

上記のフォーマットの加えて、フォントや見栄えにも一定のルールを設けました。

フォント

見やすいとは

人それぞれ感性は異なるので一概に言えませんが、
一般的に角張ったフォントよりも丸みのあるフォントがドキュメントには好まれる傾向になると判断しました。

理由

丸みのあるフォントは継続視認性が高く、読みやすい
ドキュメント全体が柔らかいイメージになる

角張ったフォントの適正

すべて丸みのあるフォントが良いわけではなく
以下のようなケースでは角張ったフォントが活きてきます。

強調したい単語や一文
公的な文書として硬い印象を与えたい

アプリ単位の適正フォント

利用頻度が高いと想定されるアプリケーションのフォント例を以下に記載します。

アプリ	OS	フォント
googleスプレッドシート	win/mac	・M Plus 1P メイリオやヒラギノ丸ゴシックに相似
EXCEL・PowerPoint	win	・メイリオ資料向けとしてよく推奨されるフォント等幅フォント・Meriyo UI 文字間スペース詰めフォントメイリオよりも同じスペースに記載できる文字数が多い視認性はメイリオのほうが高い
EXCEL・PowerPoint	mac	・ヒラギノ丸ゴ Pro N 等幅フォント

色（文字・背景）

基本は3色までの利用としました。

ベースカラー
- ドキュメントの基本色
- 色は任意だが、派手で目が痛くなるような配色は避ける
- 寒色かつ暗色が一般的
補色
- ベースカラーの反対色
  - ベースが青系なら、補色はオレンジ系など
- 強調表現に利用する
個別強調色
- 特別に強調したい箇所に利用する
- 一般的には赤系の色

結果

最初はフォーマットに従ってドキュメントを作成することに慣れていないこともあり
フォーマットを用意してからすぐに劇的な変化があったわけではありませんでした。
しかし、少しずつよくなっていったことも確かです。

クライアントや上長から
「書いてることや言ってる意味が全然わからないんだけど？結局何が言いたいの？」
と言ったようなそもそものご指摘を頂く機会が減少してきたと思います。

また、新規参画者の方からも
「これってどこ見たらわかりますか？」
と言った質問にもドキュメントのリンクを送れば
不明点が網羅的に解決できることが増えてきて追加の質問も減ってきました。

今では一定の効果があったように感じています。

さいごに

とは言え、ルールやフォーマットだけですべてを解決するのは難しいこともあると思います。
やはりプロジェクト全体・チーム全体が同じベクトルで大切だと思えてこそだと思うので
地道にドキュメントの大切さを発信し続け、
文化の醸成を促していくことが一番大切なのだとも思います。