エンジニアであれば、どなたでも多くのドキュメントを読む機会はあると思われます。

『ドキュメント』とは資料的な文章を意味しており、主にIT業界におけるドキュメントとしては、以下の種類が挙げられます。

◆設計書

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

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

◆計画書

システムの導入スケジュール、システム移行計画の立案から、

プロジェクトのメンバーの人数・日程といった計画書や、

ユーザー向け、開発チーム内部向けなど、様々な計画書があります。

◆提案書

ユーザーに対しての新規開発の提案や、

既存システムの問題点などを解消するための提案等を行うドキュメントです。

◆ユーザーマニュアル

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

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

◆報告書

新システムの各種テスト結果報告から、

トラブルが発生した場合のユーザーに対しての報告まで、

場合により様々な報告書があります。

ドキュメントとは、「何が正しいのか」を判断するものであり、

ユーザーに確認して頂いた、という覚書でもあります。

システムは平均で約5年間は使用されることを想定されており、

場合によって10年以上使用されるシステムもあります。

システムに不具合らしい事象が発生した際、

「それが本当にユーザーが当初から求めていた仕様なのかどうか？」

それがドキュメントに記載されていないと、判断がつきません。

長期システム運用を踏まえた場合は、開発側に余計な稼働負荷を掛けない、

「開発者を守る」保険にもなります。

これらのドキュメント作成において、一番重要なポイントは

『誰が読んでも全体像が把握・理解できる、見やすいドキュメントを作ること』です。

全体像がつかめないと、どんなに詳細が丁寧に記載されていてもなかなか頭に入っていきません。

また、「である調・ですます調」で揃えたり、「主語・述語の関係に注意する」や、「誤字・脱字に気を付ける」等、文単体の質を上げることも当然重要ですが、

ドキュメントを分かりやすいものにするためには、まず全体像を把握しやすいように作っていくことが大事です。

ドキュメントを全体的に見やすくすることにより、

◆誤解によるミスを防ぐ

◆手順に対しての疑問点を減らすことができる

◆作業効率が上がる

などのメリットがあります。

見やすいドキュメント作成のために念頭に置くこととして、主に以下が挙げられます。

・冒頭に概要を記載する

・目次を付ける

・見出しや箇条書きを付ける

・フローや図、画像を多く記載し、印象に残りやすくする

・作業影響を記載する(※作業手順書等の作成)

システムを扱う業界によって、専門用語の知識が必要な場合もあり、

基本的なIT知識も読み手には必要とされますが、

大前提として、『誰が読んでも理解できる内容』を心がけてドキュメント作成することが重要となります。

今回、ドキュメント作成における重要点や、工夫すべきポイントを整理し、個人的に考え感じたことは、

エンジニアには当然専門スキル・技術が必要ですが、

ドキュメント作成スキルのような、総合的な『ビジネススキル』を磨くことも改めて大事であると実感致しました。

自分も、普段から読書したり、様々な文書・記事を読んだりと、自身の文章能力を上げて、

専門性の高い難しい内容でも、初心者の方から、どなたから見ても分かりやすく理解できるドキュメントを作成を心がけていきたいです。

参考：苦手なエンジニアが多いドキュメント制作スキル (eng-entrance.com)

  ：わかりやすいドキュメントを書くには 〜 全体像を把握できることが重要 - Qiita