forkwell ドキュメント作成の基本を見て-学習メモ-
はじめに
新卒SIエンジニアがYouTube動画 https://www.youtube.com/live/lTsfCzqeHQA?si=dLNbdbobtdtoNiJP を視聴して作成したメモです。
動画を閲覧した感想
以下の4点の感想を抱きました。
1. ドキュメントの認識相違
ドキュメントと聞くと、SI系エンジニアはExcel方眼紙で作られた設計書（例：外部設計書）を想像しがちです。そのため、「Excelでどうシステムを表現するのか」という具体的な話題を期待しました。しかし、動画の内容はライティング全般にわたる高度な視座のもので、驚きと新たな発見がありました。
2. ライティングスキル≒コミュニケーションスキル＝重要
テキストベースのやり取りが主流の現代社会では、ライティングスキルはコミュニケーションスキルそのものと言えます。ドキュメントに限らず、あらゆる場面で役立つ汎用的なスキルだと再認識しました。
3. 新卒3年目以内で身につけておきたいスキル
ライティングスキルは若いうちに習得すべきです。キャリアが進むにつれて、指摘を受ける機会が減り、スキルの伸びが鈍化するため、新卒3年目以内に習得することが重要だと感じました。
4. 実務上意識すべきは速度
動画では理論的なポイントが多く述べられていましたが、実務ではすべてを意識するのは時間的に難しい場面もあります。そのため、基本スキルを習得した後、自然に構造的な文章を書けるレベルまで昇華する必要があると考えます。
ドキュメント作成の基本
ドキュメントを作成する際は、適切な構成を設計することが重要です。構成は、情報を効果的に伝え、目的を達成するための骨組みとなります。
1. ドキュメントの目的
ドキュメント作成の主な目的は次の通りです：
- 読者に見てもらい、内容を正確に理解してもらうこと。
- 情報をわかりやすく伝えることが最優先です。
2. ドキュメントの特徴
目的を達成するため、ドキュメントには以下の特徴が求められます：
-
目的の達成が最優先
- 読者が知りたいことに的確に応える内容を用意する。
-
情報の正確性
- 誤解を生まない表現と、正しいデータや事実に基づいた記述。
-
効率的な伝達
- 読者が無駄なく必要な情報を得られるよう工夫する。
3. ユーザビリティの高い文章を書くポイント
(1) 情報を整理する
文章を書く前に、情報を整理し、何を書くべきかを明確にします。
考えるべきこと：
-
What（何を伝えるか）
例: ドキュメントの主題は何か？ -
Why（なぜそれを伝えるのか）
例: 読者にどのような価値を提供するのか？ -
How（どうやって伝えるか）
例: どの順序で説明すれば理解しやすいか？
(2) 適切な章立てを行う
ドキュメントのタイプによって章立てを工夫します。
例: マニュアル
- 機能の利用目的（What）
- 機能の詳細説明（Why）
- 操作手順（How）
例: 企画書
- 企画の目的（What）
- 企画の概要（Why）
- 実行計画（How）
(3) 抽象と具体の整理
抽象的な概念と具体的な内容を分けることで、情報をわかりやすく整理します。
-
抽象的な内容（全体像）
例: 「この機能は業務の効率化を目的としています。」 -
具体的な内容（詳細）
- 具体①: 「データを自動入力する仕組みを提供します。」
- 具体②: 「手動入力の手間を削減し、平均30分短縮できます。」
4. ドキュメント構成に落とし込む
情報を整理した後は、以下のような構成を作成します。
例: マニュアルの構成
-
はじめに
- このマニュアルの目的
- 読者が得られるメリット
-
機能の概要
- どんな機能か？
- どのような場面で役立つのか？
-
操作手順
- 操作の流れをステップごとに解説。
- 必要に応じて図や具体例を挿入。
例: 企画書の構成
-
企画の目的
- 何を実現するのか？
- 現状の課題や背景を説明。
-
企画の概要
- 提案する内容の全体像を簡潔に説明。
-
実行計画
- 具体的な実行方法。
- 必要なリソースやスケジュール。
5. まとめ
ドキュメントの構成をしっかり考えることで、情報の整理と伝達がスムーズになります。また、以下のポイントを意識することで、より伝わりやすいドキュメントを作成できます：
- 情報を整理する際は「What」「Why」「How」を意識する。
- 適切な章立てと文章構造を設計する。
- 抽象と具体のバランスを取る。
Discussion