システム開発のドキュメントは『いつ・どれくらい』作るべき?

2015年11月7日に投稿 → に更新

PCを使う女性

「ドキュメント作るのめんどくせー」
「どうせ後で仕様変更するんだからドキュメント書くだけ無駄じゃね?」
「そもそも作るべきドキュメントの正解が分からない…」

システム開発において「ドキュメントをどれくらい作るべきか?」って永遠のテーマですよね。絶対的な正解はなくてプロジェクトによって変わりますからね。

私なりの考えを紹介します。

ドキュメントには2種類がある

開発に必要なドキュメントと、運用に必要なドキュメントです。

開発用ドキュメント

システムを開発するにはシステムの要件を定義して、そこから機能を導き出し、詳細化してプログラムの仕様に落とし込み、システムを実装します。

前工程のドキュメントを元にして次の工程のドキュメントを作成します。最終的にはプログラムの仕様書が出来上がり、それを元にプログラムを作るわけです。

つまり要点は、次の工程を進めるためのドキュメントを作るということです。

運用用ドキュメント

こちらは開発に必要なドキュメントとは性質が異なります。

次の工程のドキュメントを作るためのドキュメントではなく、システムを運用するのに必要なマニュアルを作ります。

ですから、運用する人が分かるように書くことがポイントです。運用する人がアルバイトの学生やIT知識のないパートのおばさんの場合もあります。

  • 専門用語をできるだけ使わない
  • 誰が読んでも同じ解釈ができるように書く

などの配慮をするとよいでしょう。

顧客に開発ドキュメントと運用ドキュメントの『違い』を認識させる

顧客の中にはこの違いがわかっていないため、開発用ドキュメントなのに、

  • 非エンジニアが読んでも意味が分かるように書いてくれ
  • 図などをもっときれいに書いてくれ

などと要求してくる人がいます。これは明らかに間違いです。

開発用ドキュメントは、開発に使うものなのでエンジニアが読むものです。ですから、エンジニアにしか分からない専門用語を使って構わないし、図形の線がちょっとくらい曲がっていたり、見栄えが悪くても構わないのです。

運用ドキュメントはシステムが完成してから作るべし

顧客の中には、「開発時に作ったドキュメントを運用でも使えるようにしたい」と言う人がいます。「仕様書にはシステムの機能の説明があるのだから、運用でも使えるはずだ」という主張です。

これも間違いです。なぜかというと、

1.仕様書には運用に関係のない情報が多すぎる

運用に必要な情報はシステムの「使い方」です。

仕様書を読めば確かにシステムの使い方は分かりますが、仕様書にはシステムの「作り方」、実装方法が書かれています。

実装方法を読んでシステムの使い方を理解するのは非常に難しく効率が悪いです。

2.システムが完成するまでに仕様変更が多かれ少なかれ必ずある

仕様書に運用に役立つ情報(システムの使い方等)を追加で書いていくとします。

開発の途中で仕様が変わると、システムの使い方の説明も変えなければなりません。

ですから、運用マニュアルは開発が終わってから作るべきなんです。

話の通じない顧客に対処する方法

  • 「自分が楽をしたいからドキュメントを減らそうとしてるんじゃないか?手抜きだろ?」
  • 「俺は客なんだ、なんでお前らの意見を俺様が聞かなきゃならないんだ!?」

こんなことを言う顧客は実際います。この場合どうすればいいでしょうか?

私なら転職します。

私も今まで散々顧客を変える努力をしたことがあります。丁寧に必要なドキュメントとそうでないものの違いを説明しました。

しかし、聞く耳を持たない人っています。ですから、こちらから提案して、懸命な説明を尽くしても、受け入れられない場合は、別の職場に移ることが賢明です。

自分に合った職場って探せばちゃんとありますからね。

転職活動はやってみるとかんたん!

私自身3回ほど転職してるんですが、思ってたよりかんたんで、転職エージェントを使ったらあっという間でした。

エージェントが応募先候補の選出から、面接の日程調整までやってくれるので、こちらから動かなくても半分くらい自動的に進む感じで楽でした。しかも今は好景気で売り手市場なので転職するのにちょうど良い時期です。

レバテックキャリアっていうエージェントがおすすめです。

このサービスを運営しているレバレジーズという会社はシステム開発もやっているので、現場の仕事をよくわかってくれてますし、ヒカ☆ラボというIT系の勉強会なども主催していたりteratailというプログラマー専用の質問サイトを運営してて好感が持てます。求人案件もWebやスマホの面白い仕事が多いのでいいと思います。

あとホームページ見ると分かるんですが、若くて美人の担当者が多いのもナイスなんです!私の場合(たぶんあなたも)、担当者が美人だと転職活動のモチベーションめちゃ上がりますからね笑

なので、レバテックキャリアのホームページ見てみてください。「ホントだ、美人じゃん♪」ってきっと思うはずです笑

職務経歴書の作り方がわからないという方は、私の使っているテンプレートを使ってみて下さい。

地方在住の人にも使える転職エージェントがある!

レバテックキャリアは東京・大阪近郊向けサービスなので、地方在住の方には全国の求人を扱っているワークポートがおすすめです。利用者の評判がめっちゃいいのでホームページ是非見てみてください。

人脈がなくてもフリーランスになれる!

フリーランスになりたい方にはギークスジョブがおすすめです。人脈がなくてもギークスジョブに登録するだけで案件を紹介してもらえます。案件の希望(どんな技術を使っているか、残業が少ないこと)等も聞いてくれるので、やりたい仕事が出来ます。対象地域は東京・大阪・名古屋・福岡近郊です。

「派遣社員」なら正社員とフリーランスのいいどこ取り!

フリーランスになりたいけど、確定申告とかめんどくさいなという方には派遣社員がおすすめです。

派遣ってネガティブなイメージありますが、ITエンジニアの派遣社員ならやりたい仕事を選べて、給料も悪くないですし、確定申告や年金、健康保険も派遣会社が入ってくれるのでいいと思います。

私の先輩でフリーランスになった後、派遣社員になった人がいるんですが「自由かつ煩わしい手続きがなくて最高」って言ってました!リクルートITスタッフィングに登録するだけでかんたんに派遣社員になれます。

私(やまろう)への相談メールも募集中

転職や仕事術、勉強法等について質問や相談がありましたら、以下のメールフォームからぜひご連絡ください。
経験者ならかんたんに解決できる相談って多いのでお気軽にどうぞ!こう書いてもなかなかメールくれる人って少ないのでホント気軽にメールしてくれると嬉しいです。

メールアドレス (必須)

相談内容

たまに間違ったメールアドレスを入力されていて返信できない場合があります。一週間経っても返信がない場合、メールアドレスを確認の上、再度送信をお願いします。

エージェントを使った方が転職活動は楽です

東京・大阪近郊のイケてるIT企業に転職したい人には『レバテックキャリア』

 東京・大阪近郊のエンジニア経験者向け転職サービスです。

このサービスを運営しているレバレジーズという会社はシステム開発もやっているので、現場の仕事をよくわかってくれてますし、ヒカ☆ラボというIT系の勉強会なども主催していたりteratailというプログラマー専用の質問サイトを運営してて好感が持てます。求人案件もWebやスマホの面白い仕事が多いのでいいと思います。

ホームページを見ると分かるんですが、若くて美人の担当者が多いのもナイスなんです!私の場合(たぶんあなたも)、担当者が美人だと転職活動のモチベーションめちゃ上がりますからね笑

エンジニア未経験の方や地方在住の方にはワークポートというエージェントをおすすめします。

エンジニア未経験の方や地方在住の方には『ワークポート』

全国の求人を扱っていて、しかもITエンジニア未経験の人にも転職支援をしてくれるエージェントです。

未経験の人はサポート対象外のエージェントが多い中、ワークポートは未経験者を支援し転職を成功させています。

未経験の方こそエージェントから職務経歴書の作り方や面接の仕方のレクチャーを受けた方がずっとうまくいきます。

『派遣社員』なら正社員とフリーランスの『良いとこ取り』!

  • 「フリーランスになりたいけど、確定申告とかめんどくさいな」
  • 「定時帰りできる職場や、時短勤務がしたい」

という方には派遣社員がおすすめです。

派遣ってネガティブなイメージありますが、ITエンジニアの派遣社員なら

  • 時給が高く、給料も悪くない
  • やりたい仕事を選べる
  • 確定申告不要(派遣会社がやってくれる)
  • 厚生年金、健康保険も派遣会社が入ってくれる

ので、正社員とフリーランスのいいとこ取りな、とてもいい選択なんです。

 - 仕事術