エンジニアもドキュメント制作技術を高めよう！具体的な高め方とおすすめ本を紹介

エンジニアは、システム開発のスキル以外に必要なスキルがあります。それは、「ドキュメント制作技術」です。

ドキュメント制作が得意になると活躍の幅が広がるので、スキル書くとくに役立つ書籍や講座なども合わせて紹介します。

エンジニアもドキュメントスキルが必須

エンジニアは、スキル開発以外に「ドキュメントスキル」も必要です。ドキュメントは、「きちんと動くシステムさえ創ればドキュメントは程々でいい」と思ってしまうかもしれませんが、必要最小限の労力をもって作成する必要があります。

システム開発においての「ドキュメント」は、次のような種類のものがあります。

それぞれについて簡単に解説します。

ドキュメント①：設計書

設計書には、「要件定義書」「基本設計書」「プログラム定義書」「テスト仕様書」などのシステム仕様を定義するための文書があります。設計書に不備・設計バグが生じた場合にプログラム作成やテストなど、下流工程に大きな影響を与える可能性があります。

ドキュメント②：計画書

計画書は、「システムの導入スケジュール」「システム移行計画の立案」などの文書です。スケジュール以外に、開発メンバーについて「いつ」「どの時」「何人必要」などといった開発計画（アサイン計画）を行うこともあります。その他、「ユーザー向け」「開発チーム内部向け」など対象が異なる計画書を制作する必要があります。

ドキュメント③：提案書

提案書は、「ユーザーに対する新規開発の提案」「既存システムの問題点を解消するための提案」を行う文書です。新規システムを導入検討している企業に対して「提案依頼書（RFP）」の提示をシステム開発企業に求める流れもあります。

RFP（Request for Proposal）とは、新規システム構築に必要なハードウェア・ソフトウェア・サービスの内容、契約条件などを記載しています。営業担当者が作成することが多くありますが、エンジニアが作成することもある文書です。

ドキュメント④：ユーザーマニュアル

ユーザーマニュアルは、「新システムの使い方」などをまとめたマニュアルです。「システムの概要」「システムの目的」「書く画面」「帳票の説明」など、システムに関してユーザーが行わなければならない項目の手順を記載します。

ドキュメント⑤：報告書

報告書は、「新システム各種テスト結果報告」「トラブル発生時、ユーザーに対する報告」など、様々な報告書が必要となります。分かりやすく的確に報告をまとめる必要があるので、報告書も大切な文書です。

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

ドキュメントは、開発者を守るために大切なものです。もし、部署異動などによって、担当していたシステムの保守担当から外れた時に、公認の担当者が自分レベルにまで該当にシステムに精通していなかった時、「コードから仕様を把握する」ことが現実的に無理です。

また、システムは5年間使用することを想定しているものの、10年以上使用し続けるシステムもあります。不具合が生じた時、「本当にユーザーが当初から求めていた仕様だったか」という判断に辿り着いた時、ドキュメントに記載がないと不明なままになります。

ユーザーは、プログラムを見て判断するのではなく、設計書などユーザーが認証したドキュメントを見て判断するします。結果、不具合が「設計書」「打ち合わせ議事録」にも記載されていなかった場合「プログラムのバグ」という扱いになります。バグの修正は、基本的に「無償」で行う流れが一般的で、バグ修正のために行うデータ修正や現地対応の費用・ユーザーへのバグ終息報告資料作成などの稼働が発生してしまいます。

長期のシステム運用を踏まえた場合、開発者に余計な負荷を与えないようにするための「保険」としてもドキュメントはなるので重要です。

ドキュメントの特徴

システム開発系のドキュメントでは、「自分以外の誰かが参照・更新する可能性がある資料」です。

抜け漏れ・読み手によって解釈が異なるような状況があってはいけません。抜け漏れがあった場合、要件の未達成から手戻りになってしまいます。また、解釈が異なる記述をした場合、のちの工程への不具合が引き起こされます。書き手が納得いくまで時間をかけられるわけでもないので、「生産性を高める工夫」も必要です。

ドキュメントに求められること

システム開発系のドキュメントで求められることは、「品質」「読み手にわかりやすいこと」などです。

という品質などです。その他、タイトルや表紙、インデント、ページ番号なども気にして制作することで、他の人が見てもわかりやすいドキュメントになります。

上記を気にすることが大切です。

きちんとドキュメント制作が行われ、維持されていれば「開発」「運用」「保守」などの作業において、とても頼りになります。何が起こったのかを探るために重要でもあり、ずっと維持されなくてはならない大事な資産です。

ドキュメントを作成する時のポイント

ドキュメント作成する中での大切なポイントを紹介します。

それぞれについて解説します。

フローを最初に決める

ドキュメントを作成する時に、まずフローを決めましょう。

というメリットがあります。フローを冒頭につけて書類を作成することで、他の人と作業する時など、説明しやすい点もメリットです。フローは、ブログの見出しを決めるような感覚で検討しましょう。

ターゲットを絞る

ドキュメントを確認するターゲットを絞りましょう。人によって技術レベル・理解力が異なるため、ターゲットを絞って作成することで、その人に合うドキュメントを作成できます。

ポイントを意識することで、見る人に合わせた内容のドキュメントが作成でき、プロジェクトを推進する上で効率的に物事が進みます。

全体的に見やすくする

最後に大切なポイントは、全体的に見やすいドキュメントを作成することです。

上記のメリットがあるので、全体的に見やすいドキュメント作成が大切となります。フローや図を載せたり、画像を多用することでイメージしやすくなる点も魅力的です。また、見出し・箇条書きなどを用いることもポイントです。

ドキュメントスキルを身につける方法

ドキュメントスキルを身につける方法について以下2点で解説します。

• 書籍で勉強する
• Udemyで学習する

それぞれについて解説します。

書籍で勉強する

書籍でドキュメント作成についてのスキルを学ぶこともおすすめです。ここでは、書籍を2点紹介します。

技術者のためのテクニカルライティング入門講座

「文章は倫理的かつ簡潔に記述すること」という当たり前のテクニックを学ぶ機会が少ないのが日本です。この書籍では、テクニカルライティングを通じて、相手に伝わる技術文章を効率よく書けるようになるテクニックを紹介しています。

ユーザーマニュアル、障害報告書、提案書などの実務直結の文例を掲載しているので、業務に役立てられます。

まんがでわかる　理科系の作文技術

大ベストセラーの新書「理科系の作文技術」のまんが化です。漫画で分かりやすく紹介しています。「明快・簡潔な表現」を追求し、役立つエッセンスがたくさん詰まっています。「最強の文章術」が論文・レポート・ビジネス文書など、あらゆるシーンでの文書作成を手助けしてくれます。

漫画では、IT企業で契約社員として働き始めた主人公が、「仕事の文書」で求められる文書が全く異なるものであったことをしり、上司からの指導のもと奮闘するストーリーになっています。「相手に伝わる」文章スキルを身につけていきます。

Udemyで勉強する

Udemyで、学習する方法も合わせてご紹介します。Udemyは、世界最大級のオンライン学習サイトです。動画で分かりやすくテクニックを身につけられます。ここでは、3つのおすすめ講座を紹介します。

参考：Udemyとは？Udemyで学習するメリット、おすすめ講座を紹介！

ITエンジニアにこそ伝えいた文章術講座。実例多数！10年後も使える文章術を基礎から応用まで5ステップで学べる実践講座です

学習内容：文章術の基礎スキル、文章スキルの現場での実践方法、ロジカルシンキングの基礎知識、思考の整理法と文章への書き起こし方、伝わる文章の書き方

エンジニアに求められる「伝える力」を多角的な視点で捉え、筋肉質な文章が書けるようになります。実際の現場ですぐに使える応用例なども効率的に学べる講座となっています。

手を動かして学ぶITプロジェクトの資料作成！システム開発のドキュメンテーション技術と成果物テンプレート

学習内容：ITプロジェクトの中で、考えなければいけないことがわかる・フェーズ毎に、どんな資料を作ればよいのかがわかる・システムの設計書や会議資料を読んで、全体像を理解できるようになる・論理的にわかりやすい資料のまとめ方がわかる

学べる機会の少ないITプロジェクトの資料作成を学べます。プロジェクト計画、要件定義、設計、テスト、移行、運用など開発現場のリアルな視点で徹底解説しています。

誰でもわかる システム開発入門

学習内容：システム開発のおおまかな流れ、様々な仕様書の種類・役割、システム障害発生時の対応方法・手順、セキュリティ対策が有効になっているかの確認、ネットワーク構築の考え方など

システムエンジニア、プログラマーに必須の「システム開発」「システム仕様書」「システム運用管理」「ネットワーク構築」「システム監査」などの基礎知識を身につけられます。

おすすめドキュメント作成ツール

ドキュメントはWordで作成する文書をイメージすると分かりやすいかと思います。最近は、Wordよりも簡単で気軽に作成できるドキュメント作成ツールが多くあります。ドキュメント作成ツールを利用することで、「テンプレート機能」などの便利機能がある点がメリットです。毎回記載する項目をゼロから作成する手間がありません。

ここでは、おすすめのドキュメントツールを4つ紹介します。

• Googleドキュメント
• Qast
• NotePM
• Qiita:Team

Google ドキュメント

Googleドキュメントは、Googleが提供しているドキュメントツールです。編集ツールやスタイル設定ツールを使用することで、テキスト・段落の書式が簡単に設定できます。ドキュメントの作成が楽になるので、楽しく制作ができます。すべての機能を無料で使えます。いつでもどこでも、ドキュメントにアクセスできたり、オフラインでも作業が継続できる点など利便性が高い点も魅力的です。

Qast

Qastは、Qastは、業種や職種を問わず直感的に操作できるシンプルなUIが特徴的なドキュメントツールです。初めてツールを使う方やITに慣れていない方でも直感的に操作ができます。また投稿を見逃さないリアルタイム通知などもあるので、チームで使う時でもリアルタイムで共有できます。社内版知恵袋なども作成できるので、一部の人だけでなく誰でも気軽に発信できます。

NotePM

NotePMは、Wikipediaのように社員が様々な情報を書き込み、蓄積できるドキュメントツールです。編集・検索・閲覧すると社内の「知りたいこと」が簡単に確認できます。Webでマニュアル作成も行えます。高機能エディタとテンプレートでフォーマットを標準化できます。情報の投稿・更新が簡単な点が魅力的です。Wiki上でファイル共有ができ、「社内規定」「マニュアル」「提案書」などを共有しやすいです。

Qiita:Team

Qiita:Teamは、簡単に書ける・共有できる「社内向け情報共有」サービスです。何でも書きたくなる心地よさ、フィードに共有するだけのシンプルさなどが人気の秘訣でしょう。暗黙知をなくし、信頼感のあるチームを作成する場を提供しているドキュメントツールです。日報や議事録などもテンプレート機能で統一できます。こまめな情報共有ができるので、その場でコミュニケーションを取れる点も魅力的です。

まとめ：ドキュメント制作技術を高めよう！

エンジニアにとってドキュメントスキルが重要であることがお分かりいただけたと思います。ドキュメントスキルを上げて、制作技術を高めることでチーム内の士気も高まる可能性があります。

ドキュメントツールなども活用しながら、スキルを磨いていきましょう。