苦手なエンジニアが多いドキュメント制作スキル

From: リスキルテクノロジー 松田航
新宿本校にて、、、

IT技術者にとって必要な事。

設計スキルや
プログラミングスキルなど
直接システム開発に必要なスキルはもちろん必要です。

しかし実際のシステム開発においては、
一見するとITスキルとは直接関係がないようなスキルも必要になります。

数え上げるとキリがない程あるのですが、
まずはそのような間接的に必要となるスキルのうち...

「ドキュメントスキル」

...についてお話ししましょう。

多くの技術者が苦手意識を持つ
ドキュメントスキル

ドキュメントスキル！

この名を聞いただけで
嫌な顔をする技術者はかなり多いです（笑）

多くの技術者はドキュメントの作成を苦手としています。

「ドキュメント」とは資料的な文章を意味しますが、
システム開発におけるドキュメントとしては以下の種類が挙げられます。

(1)設計書

要件定義書や基本設計書、
プログラム定義書やテスト仕様書など
システムの仕様を定義するための文書群です。

上流工程で作成される為、
設計書に仕様不備や設計バグがあった場合には
プログラム作成やテスト等、下流工程に大きな影響を与えます。

(2)計画書

システムの導入スケジュールや
システム移行計画の立案などといったものから...

プロジェクトにおいて、
開発メンバーがいつ、どのタイミングで、何人必要なのかといった…

内部的な開発計画（アサイン計画と言います）など、
ユーザー向け、開発チーム内部向けなど、様々な計画書があります。

(3)提案書

ユーザーに対する新規開発の提案や、
既存システムの問題点などを解消する為の提案などを行うドキュメント。

最近では新規システムの導入検討をしている企業が
「RFP（提案依頼書）」の提示をシステム開発企業に求め傾向があります。

RFPには新規システムに必要な
ハードやソフト、サービスの内容や契約条件などを記載しており、
多くの場合は営業担当が作成しますが、SEが作成する場合もあります。

(4)ユーザーマニュアル

新システムの使い方などをまとめたマニュアルです。

システムの概要や目的に始まり、
各画面や帳票の説明、その他システムに関して
ユーザーが行わなければならない事項を手順としてまとめます。

(5)報告書

新システムの各種テスト結果の報告から、
トラブルが発生した場合のユーザーに対する報告まで、
場合によってさまざまな報告書が必要となります。

このように、システム開発において、
多くの文書を作成する必要がある事をおわかり頂けたでしょうか。

ユーザーによって求められる文書の種類は異なりますが
多くのドキュメントを作るとなると、かなりのマンパワーが必要です。

基本的にSEやPGには...

「きちんと動くシステムさえ作れば、ドキュメントは程々で良い！」

...という考えを持った人が（残念ながら）多いです。

そのためドキュメントについては
必要最小限の労力をもって作成する傾向があり...

必要最小限の労力しか費やさない為に
ドキュメントスキルが磨かれず、苦手意識を持つ人が多いのが現状です。

作成負荷を減らしたいからドキュメントを簡素化
それが逆に稼働負荷が掛かる結果を招く事も！

開発案件によっては
納期までのスケジュールが短いため...

「ドキュメント作成量をできるだけ減らしたい！」

そういった現場の声があるもの事実。

現場の声としては理解できるのですが、
ドキュメントをしっかり作成しない事が原因で、
全体的に開発稼働が余分にかかってしまうというケースもあります。

例えば、以下の様な画面設計書があるとしましょう。

顧客管理するシステムの、顧客情報を登録する画面です。
画面の下表は、設計書の説明内容になります。

一応、画面設計書っぽく見えなくはないですが
正直言って、この設計書を渡されたプログラマーは困惑します。

顧客コードは何ケタなのか？
顧客名は何バイトまで入力できるのか？
顧客名カナは全角なのか半角なのか？

このような確認事項が増える事により
開発時間がズルズルと遅れてしまうケースもあります。

では、先ほどの顧客情報登録画面を以下の様にしたとしましょう。

～中略～

この状態でもプログラマーからの質問は発生するでしょうが、
先ほどの例と比べると各段に質問の量は減ります。

ドキュメントを作成するにあたり
簡素にできる部分は簡素にして構いません。

１～１００まで記述すれば
ドキュメントの作成稼働だけについやされて
他の作業を行うのに支障をきたします。

ただ、「時間がないから」という理由で
本来記述しておくべき内容を書かないというのは…

あなたにとってもチーム全体にとっても、
そしてシステムにとっても良いことではありません。

ドキュメントは開発者を守るもの

IT技術者の中には...

「とりあえず動くプログラムがあれば良いのでは？」

...という発言をする方もいます。

その理由は...

「何か不明な点があればプログラムソースを見れば良い」

「ソースがその処理内容の仕様なのだから」

...という意見から出ています。

その意見にも一理ある様に見えますが、
残念ながら正しいとは言えません。

例えば部署異動などで
あなたがそのシステムの保守担当から外れたとしましょう。

後任の担当者が
あなたのレベルにまで該当システムに精通していない場合、
コードから仕様を把握しろというには、現実的に無理があるのです。

また、システムというのは
平均すると約５年間は使用する事を想定されており、
場合によっては１０年以上使用されるシステムもあります。

システムに不具合らしき事象が発生した場合、
それが本当にユーザーが当初から求めていた仕様なのかどうか？

ドキュメントに記載していないと判断がつかないのです。

ユーザーはプログラムの中身までは見ません。

ユーザーはプログラムを見て
正しいかどうかを判断するのではなく、
設計書などユーザーが認証したドキュメントを見て判断します。

現在起きている不具合らしき事象が
設計書にも打ち合わせ議事録にも、
どのドキュメントにも記載されていない場合、
プログラムのバグとして扱われてしまうケースが多いです。

バグ修正は基本的に無償で行う必要があり、
またバグ修正の為のデータ修正や現地対応の費用、
ユーザーへのバグ終息報告資料の作成など、多くの稼働が発生します。

ドキュメントというのは、
何が正しいかを判断するものであり、
ユーザーに確認してもらったという覚書でもあり...

長期のシステム運用を踏まえた場合、
開発側に余計な稼働負荷を掛けない保険にも成り得るのです。

誰でも理解できるドキュメントが大原則
専門性だけでなくビジネス力も身に着ける

ドキュメントを作成するにあたり
守らないといけない大原則があります。

それは...

「誰が読んでも理解できるドキュメントを作る」

...という事です。

もちろん、
システムが扱う業界によっては
専門用語の知識が必要な場合もあり、
また基本的なITの知識も読み手には必要とされます。

ですが、
システムはひとりで作るものでもなく、
ひとりで使用するものでもありません。

設計書であれば...

プログラマーには
プログラム作成の際に作りやすいように、

ユーザーには処理内容を
わかりやすく理解してもらうための工夫が必要。

計画書であれば...

どのような計画でプロジェクトを進め、
どのタイミングでどのようなイベントが発生するのかなど
誰が見ても理解できる計画書。

提案書であれば...

提案の目的を明確にし、
費用やスケジュールなどを考慮した上で
提案内容を実現する事によるメリットが伝わりやすい様に。

ユーザーマニュアルであれば...

たとえば新人のユーザーであっても
マニュアルがあればある程度の操作ができるような
操作方法や手順が明確に記載されている、読みやすいマニュアルを。

報告書であれば...

現在発生している事象の説明に始まり、
原因と結果、影響範囲、対応内容、対応時間など
ただ報告するだけの書類ではなく、どう対処するかまで報告すること。

基本的には、
誰が読んでも理解できる内容を心がける！

これがドキュメント作成するにあたって肝心な事です。

そしてドキュメントスキルを向上させる為にもうひとつ...

ダラダラと文字だけを書き連ねる！

…といったドキュメントは作成しないようにしてください。

図やグラフなど、
視覚的に把握しやすい資料があれば、
それは読み手の印象に残りやすくなります。

直接的な関連はなくとも、
ドキュメントの印象付けとして画像を挿入するのも良いでしょう。

プレゼンテーションで使用するドキュメントであれば
アニメーション効果や動画を使用するのも効果的です。

未経験からIT企業に入社した場合、
最初はプログラム作成ばかり行うかも知れませんが...

キャリアを積んで行くに従い、
プロジェクトリーダーやプロジェクトマネージャーになると、
さまざまなドキュメントを作成する機会が確実に増えます。

ドキュメントの作成は手間も時間もかかり、
多くのIT技術者が苦手としているスキルです。

しかし、
誰もが苦手にしているスキルだからこそ、
あなたがドキュメント作成スキルを身に着ける価値があるのです。

そしてこのスキルは、
IT分野に限った事ではありません。
例えばあなたが独立して、起業するとした場合にもきっと役に立ちます。

IT技術者にはもちろん専門性が必要です。

しかし、ドキュメント作成スキルの様な、
総合的な「ビジネススキル」を磨くという事も
忘れないでください。

リスキルテクノロジー
松田

PS

ドキュメントの作成の仕方は、
ひとりではなかなか学べません。

ドキュメント制作も含めて学べるIT教育