はじめに
読む気を失ってしまうドキュメントや、内容がすんなりと頭に入ってこないドキュメントに出会った経験はあませんか？
あるいは、自分の作成したドキュメントが意図した通りに伝わらず、誤解された経験は？
入社以来、コーディングを中心業務としつつ、議事録や仕様書、設計書、手順書等、さまざまなドキュメントの作成・更新に携わる機会が多くありました。
IT業界に限らず、多くの社会人が日々何かしらのドキュメントを作成していると思いますが、「良いドキュメント」を作るのは意外と難しいのではないでしょうか。
先輩の指摘や既存資料の更新を通じて、読み手に伝わりやすいドキュメントを作成するには、細かな工夫が必要だと痛感しています。
この記事では、社会人2年目の新米エンジニアの視点ではありますが、私がこれまでに学んだドキュメント作成のポイントや工夫をお伝えします。特に、新入社員や若手社員の参考になれば幸いです。
偉そうに言っていますが、この記事に何か不備があってもご容赦ください…
目次
注意点と工夫
- タイポ（誤字・脱字）
- 文法・表現の誤り
- 表記揺れ
- 一文は簡潔に、ただし明確に
- 「前提知識」を疑え！
- 図や画像の挿入
- 参照先のリンクやパスを記載する
- 行・列の固定
- 項番はROW関数で振る！
- 言葉の修正はちまちましない！
- レイアウトを揃える
- 色使いを工夫
- Excelファイル保存時にセルA1を選択しよう！
おまけ
まとめ
注意点と工夫
タイポ（誤字・脱字）
タイポは気を付けていても見落としてしまいがちですよね。
私自身も過去にやらかしてしまいました…
とはいえ、「仕方ない」では済まされない場合も。
身内のみが閲覧するドキュメントならまだしも、例えば、顧客に連携したドキュメントでタイポが見つかったとしたらどうでしょう？
特に、顧客の会社名やサービス名、氏名等の固有名詞にミスがある場合、自分が恥をかくだけでは済みません。いらぬ混乱を招きますし、大変な失礼にあたります。最悪の場合、信用問題に発展する可能性も…？（少し大げさかもしれませんが笑）
ですので、細心の注意を払いましょう！
※ 特に英単語は圧倒的にスペルミスが多いです。ドキュメントでもコーディングでもよく見かけます。過信せずに、積極的に辞書引きましょう（笑）
- コピペを活用する
- 固有名詞や定義済みの言葉は、なるべく信頼できるドキュメントからコピペし、極力手入力を避ける。
- 辞書ツールを活用する
- 辞書ツールに単語を登録して変換ミスを減らす。
- 例）Microsoft IME ユーザー辞書ツール
- 声に出して読んでみる
- 黙読では気づかない間違いに気づくことも。
文法・表現の誤り
やはり、文法や表現の誤りは読みづらさに繋がります。
日常会話では問題ない表現でも、ビジネス文書では避けたいものです。
特に、個人的に読んでいてムズムズしてしまうポイントは以下の２つ。
- 改行や句読点の位置が適切ではない
-
敬体「です・ます調」と常体「だ・である調」が混在している
※ 箇条書きの場合は混在しても問題ない。
これらは基本的なことではありますが、さまざまなドキュメントを見ていると、意外と守られていないケースが少なくありません。
誤解を招かないよう、正確な表現を心がけたいですよね。
- 文章を一晩寝かせる
- 書いた直後に推敲するよりも、時間を置いてから読み直すことで冷静に誤りや不自然な表現に気づける。
- ※ 時間があれば
- WEB検索、文法チェックツールを活用する
- プライドは捨てて、どんどん使う。自分の為にもなる。
表記揺れ
表記揺れも注意したいポイントです。
同じプロジェクトでもドキュメントによって使われている用語や表現が統一されていなかったり、同じドキュメント内でさえ異なるケースも。これも個人的ムズムズポイントです。
例）
- 「commitする」／「Commitする」／「COMMITする」／「コミットする」
- 「ユーザー」／「ユーザ」（長音の有無）
- 「API」／「ＡＰＩ」（半角と全角の混在）
些細な違いと思われるかもしれませんが、こうした揺れを解消するだけで資料の読みやすさや信頼感が格段に向上します。複数人で作業するときは、事前に表記を統一するための認識合わせをするのがよいと思います。
細かいところこそ丁寧に整えていきたいですね。
一文は簡潔に、ただし明確に
文章の長さは読みやすさに直結します。一文が長いと読みたくなくなりますよね…
読んでいる途中で、結局何を言いたいのか分からなくなることも。
- 一文は簡潔にまとめる
- 文章は短くすることを意識する。ただし、主語や目的語はなるべく省略しないこと。意味が伝わらなくなってしまい、本末転倒になるので注意。
- 堅すぎる表現、難しい漢字の使用は避ける
- シンプルな表現のほうが、短時間で理解しやすく、誤解を生むリスクも減らせる。
- 主語と述語を近づける
- 文章がやや長くなる場合、語と述語を離しすぎないよう意識する。
- 他者の視点を取り入れる
- 一度誰かに読んでもらい、分かりづらい部分や改善点などをフィードバックしてもらう。
「前提知識」を疑え！
当たり前ですが、前提知識はひとそれぞれです。
「これくらい分かるだろう」「察してくれるはず」という思い込みは、誤解や混乱を招く原因となり危険です。
エンジニアと非エンジニアの顧客との間だけでなく、エンジニア間でも認識の齟齬は起こりえます。
- 具体的に書く
- 誰もが理解できるように、必要な情報を漏れなく伝える。
- 使用する技術に関する説明はなるべく省かない。
- 具体的なケースを交えて説明するとより理解が深まる。
- 用語集を作成する
- プロジェクトやドキュメント内で使用される専門用語や略語の一覧を作成し、それぞれの意味や簡単な説明を添えておく。
- 認識のズレを防ぐために、初期段階でチームメンバーや顧客と認識を擦り合わせておく。
- また、参考になるWEBサイトやドキュメントを提示すると◎
図や画像の挿入
技術的な説明や複雑な内容だと、文章だけでは分かりづらいものもありますよね。
エンジニア同士であれば分かる内容でも、非エンジニアにとっては難しいことも。
文章だけで説明しようとせず、適度に図や画像（ポンチ絵、スクリーンショット等）を挿入して直感的に理解できるよう工夫しましょう！
- 図や画像を乱用しない
- ※ 乱用するとかえって分かりづらくなる。
- 図や画像が最新の状態に更新されているか確認
- ※ 文章の更新はできていても、画像の更新だけ失念することも。
参照先のリンクやパスを記載する
参照先は文章だけでなく、きちんとパスを記載したりリンクを挿入したりするのが◎
参照先が同じドキュメント内の場合も、該当箇所へのリンクを挿入しておくと、探す手間を省けて便利です。
★ Windows PCでパスをコピーするためのショートカットキー
ファイルを選択した状態で
①Shift＋右クリック
②[パスのコピー]を選択
フォルダ階層やファイル名を含む完全なパスを簡単に取得できます！
例）
C:\Users\A_Este\Documents\Qiita\Qiita記事一覧.xlsx
行・列の固定
Excel、Googleスプレッドシート等で表を作成する際、行や列を固定するべし！
スクロールしても項目名や項番が常に表示されるため、視認性が向上して情報の関連性を把握しやすくなります。
作成した本人だけでなく、他の作業者の入力ミスや確認ミスも減らすことができます。
項番はROW関数で振る！
手入力や連続コピーで連番にするのではなく、ROW関数で振るのをおすすめします。
行を追加したり削除したりしても、前後の項番が自動で更新されるため、手動で項番を振り直す必要がありません。
また、手動で項番を振る場合、途中で番号が抜けたり重複したりすることがありますが、関数を使えばその心配がなくなります。
★ 項番を振るためのROW関数
例）
- $ = \\ROW()-1\\$
- 行番号から1を引いた値を項番として使用したい場合
- $ = \\ROW()-ROW(\$A\$1)\\$
- 任意の行から項番を始めたい場合。参照の\$A\$1が基準となり、項番は次の行から始まる。
言葉の修正はちまちましない！
特定の言葉を修正するときに、ひとつひとつ修正するのは避けるべし。
高確率で修正漏れが発生します！（経験済み）
置換の機能（Ctrl + H）を使うと、手動で修正するよりも圧倒的に効率的でおすすめ。
これはドキュメントに限らず、コーディングのときも同じです。
- 「すべて置換」には注意
- 一気に修正をかけられるので便利だが、修正が不要の箇所や部分一致のものまで修正されてしまう。
レイアウトを揃える
レイアウトが見にくい、揃っていないというのもドキュメントを読む気を失わせるポイントのひとつです。
- 開始位置を揃える
- 文章の開始位置だけでなく、図・画像の貼り付けの開始位置、図形オブジェクトの上端、左端等も揃える。
- 視線の遷移を考える
- テキストや図形の配置を工夫することで、読み手が自然に情報を追いやすくなる。
- 行間の統一
- 箇所によってばらつきがあるとムズムズする...
色使いを工夫
色使いを工夫して直感的なドキュメントを作成しましょう！
色は単なるデザイン要素ではなく、情報を伝える強力な手段です。
よく「情報の約８割は視覚から入ってくる」と言われますよね。
文字色、背景色を適切に使い分けて情報を視覚的に整理することで、重要なポイントを効果的に伝えることができます。
例）
- 赤：優先度が高い項目、重要箇所
- 黄：優先度が中程度の項目、注意喚起したい箇所
- 緑：優先度が低い項目、問題ない箇所
多色使いには注意。
特にスライドを作成するときは、なるべく4色以内に収めるようにするのが◎
色を使いすぎると情報過多になり、何が重要か判別しにくくなってしまう…
Excelファイル保存時にセルA1を選択しよう！
Excelでファイルを保存すると、最後に開いていたワークシートとアクティブセルの位置も記録されます。
したがって、セルA１を選択した状態で保存すれば、次にファイルを開いた際に必ず冒頭部分が（セルA１）が表示されるので、いちいちスクロールする手間が省けます。
※ Googleスプレッドシートの場合は自動保存ですので、セルA１を選択した状態でタブを閉じればOKです。
かくいう私も、少し前にX（旧Twitter）のこちらの投稿を見つけてから意識して保存するようになりました。
職場にそれなりにExcel使えて、僕は無能ですと言いつつそれを隠してるオッサンが一人おるな、、、
隠しても無駄だぜ、どれだけバカを装っても、整然としたファイル名、フォルダ構成、ExcelのA1を選択してから保存してるあたりから、プンプン伝わってくるぜ、、、
あと開発タブ、見えてんだよ、、、
TAKA MAN (@TAKAMAN02345158) 2024年9月26日
明確なルールではないのですが、どうやら“お作法”として巷では有名とのこと。
ちょっとした工夫ですが、これだけでスムーズに作業を再開できるだけでなく、読み手にとってもかなり見やすく、整った印象を与えることができます。一石二鳥ですね！
新人がこれを自然にできていたら「おお、やるな」「細かいところまで気を配れるやつだな」と思ってもらえること間違いなし！！
保存前の一手間、ぜひ取り入れてみてください。
- アクティブセルをセルA１に戻しておく
- 最も左側のワークシートを開いておく
- 中途半端なページからスタートにならない。
★ セルA1（ホームポジション）に移動できるショートカットキー
- Windowsの場合
Ctrl＋Home - Macの場合
control＋fn＋←
※ 先頭行を固定していると、A１ではなく直下のセルに移動します。
おまけ
ファイル連携時のtips
ドキュメントの作成が一旦完了し、同僚にレビューしてもらったり、完了報告をしたりするとき、ファイルの格納場所を一緒に連携することが一般的ですよね。
連携された側はパスをコピペすることで、すぐに該当のファイルにアクセスでき、非常に便利です。
が、ここでひとつ問題が…
Windows∔R でダイアログボックスを開き「ファイル名を指定して実行」機能を使って、例えばexcel.exe /r [ファイルパス]のように読み取り専用で開くのであれば問題ありません。
ただ、うっかりパスをエクスプローラに直接貼りつけてしまうと、ファイルが読み取り専用や新規で開かれないため、誤って編集してしまったり占有ロックをかけてしまったりすることがあります。
これを防ぐための方法として、最近いいなと思った連携方法があります。
それは、ファイルの格納場所までのパスを記載し、ファイル名は別に記載するという方法です。
例）
\common\A_Este\Documents\連携資料
・Qiita記事一覧.xlsx
開くのに少し手間が増えてしまいますが、この方法であれば、誤ってファイルを開いて編集してしまうことが減ります。また、フォルダ内の他の資料も確認しやすくなります。
時と場合によって使い分けるとよいかもしれません！
まとめ
認識を統一するためのドキュメントで認識に齟齬があると意味がありません。
コーディングだけでなく、正確な情報を伝えるためのドキュメント作成もエンジニアにとって大切なスキルだと思います。
基本的なルールを守り、ちょっとした工夫をするだけで、ドキュメントは一気に見やすくなり、評価も上がります。
今後もより良いドキュメント作成を目指して努力したいと思います。
アドバイスや気を付けていること、失敗談などがあれば、ぜひ教えてください！