tetsuwan blog

鉄ワン(@tetsuwan30)の気ままなブログ

ドキュメントスタイル・ガイドライン

本書の概要

・ドキュメントに関わる課題を、目的に応じて解決するためのガイドラインです

本書の目的

・課題を抱える対象者の負担を軽減し、より良く業務を円滑にすることを目的とします

・強制を伴ったルールではなく、内容に共感した場合に各自が利用するためのガイドラインとしています

目的別ガイドライン

【1】ドキュメントの作成

対象者
・ドキュメントを作成する人
課題
・作成する工数
・作成するハードル
・ドキュメントの内容に関する影響・責任
解決策
・テキストデータにする
(装飾やHTMLを使わない)
・パワーポイントよりテキストファイル、メールよりチャットで書く
(内容と直接関係ない要素である、表紙や冒頭の挨拶文など省くことができる)
・事前に簡素なドキュメントであることを伝えて、理解してもらう
(内容にフォーカスしてもらうことで、ドキュメントを渡す相手への配慮を省くことができる)
・ドキュメントの対象者や前提条件を記載する
(ミスリードをなるべく防ぐ、ミスリードが発生した際の影響を少なくすることで、書く責任が低減する)

【2】ドキュメントの管理・閲覧

対象者
・ドキュメントを貰う人
課題
・ファイルの容量が大きく、メールなど通信や開く際に負荷がかかる
・貰ったファイルを受け取った人が各自で保存場所を準備しなければならない
・ファイルの作成者が誰か分からず、内容を確認することができない
・手元にあるドキュメントが最新の状態か分からない
解決策
・オンラインストレージやWikiなどのURLで共有できる仕組みを使う
Googleドライブ、Box、OneDrive、Confluence、Notionなど)
(作成者や更新履歴も確認ができる方が望ましい)
・チャットにて短縮URLを使い、短い文章でも送れるようにする
(チャットに数行で記載することができ、相手が把握しやすい)
(URLで情報を連携するので、後からチャットの中を探すとことが防げる)

【3】ドキュメントの閲覧・理解

対象者
・ドキュメントを読む人
課題
・内容を読む前に、難解だと思い、そもそもドキュメントを見ない
・作成者の意図とは違う理解をしてしまう
解決策
・箇条書きにする
(見出し、見出しに付随する一覧、一覧ごとの補足など、インデントを使いリストにする)
・ドキュメントを構造化する
(見出しをつけて、概要・目的・背景・課題・詳細など、何をどのような順番で伝えたいか伝えたいか、分かりやすくする)
・平易で一般的な表現を使う
(中学生が理解できる表現で、専門用語はなるべく使わず、ドキュメント内の用語も統一して記載する)

【4】ドキュメントの検索

対象者
・自身の課題のためにドキュメントを探している人
課題
・ファイルやフォルダの階層を辿っていくため、時間がかかる
・ファイルを毎回開き、開いたドキュメントのページをめくっていき探す手間がかかる
解決策
・オンラインストレージの検索の機能を使う
(ファイルサーバの検索では十分な検索結果が出ない場合があるため)
Wikiなどのテキストデータで管理された仕組みを使う
(Confluence、Notionなど、ファイルではなくページとして管理されたものが望ましい)
(URLをクリックして、そのままページの本文が見れることで一手間省くことができる)

【5】ドキュメントの比較・更新・削除

対象者
・ドキュメントに記載する最新の情報を持っている人
課題
・ドキュメントの内容が最新でないが、更新して良いのか判断がつかない
・ドキュメントの更新をするために、ファイルを開き、保存をするのに手間がかかる
・更新すべきドキュメントのファイルがどれか分からない
解決策
・ドキュメントの運用ガイドラインを作成する
(ドキュメントの目的を明確にし、どのように作成・更新を行えば良いか記載する)
・ドキュメントの管理する単位を明確にする
Googleドライブ、Confluence、Notionなどグループやワークスペースにより、管理者・管理グループを設定する)
Wikiなどのテキストベースでドキュメントを管理する
(ファイルのような開く手間を書けないようにする)
・ファイルのバックアップではなく、更新履歴から判断できるようにする

(履歴の世代ごとに比較して差分を確認することもできるようになる)