ドキュメント整備の隠れたコスト

ドキュメント整備の隠れたコスト @silpheed_kt Keiichi Tanaka ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト 自己紹介 @silpheed_kt Keiichi Tanaka • • • • • • プログラマー インフラエンジニア ネットワークエンジニア ドキュメンター リーダー職っぽい何か セキュリティ系の会社に所属 Twitterは鍵垢です。 ssmjpのSlackでは主に #music にいます。 ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト はじめに • 本LTは録音、録画、SNS投稿OKです。 • 本LTの内容は無保証です。 • 個人の見解です（所属する組織等のそれではありません）。 • 文字ばかりです。 • ゆるいです。 • こわくないです。夏も近づいてきましたね。 ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト 「コスト」でぱっと思いつくものは？ • 想定以上の工数がかかる / 工数が確保できていない 主に新規作成時 • メンテナンスコスト（工数） 仕様変更などで更新しないといけない • ツール、設備などのコスト Microsoft Office、ドキュメントスキャナー、etc ... ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト 「コスト」でぱっと思いつくものは？ ぶっちゃけ、程度の差はあれど、 めんどくさい ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト なぜ「めんどくさい」と感じるのか 「すらすらと書けない」と「めんどくさい」 ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト なぜ「すらすらと書けない」のか 書き始めるまでにつまづくことがある。 1. ツールに慣れてない • Wordの使い方に慣れていない • ウェブアプリの使い方に慣れていない • 記法に慣れていない 2. ツールが適切に使われていない • Officeファイルの共有がオフになっている • ファイルがロックされている • 書き込み権限が付与されいなかった ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト なぜ「すらすらと書けない」のか (2) 書く内容が決まっているようにみえて、実は決まっていない。 3. 対象読者の認識 1) 同一の職責（備忘録） • 自分だけが分かればいい • 自分と同じ、近い職責の人が分かればいい 書く内容が決まっている 思ったままを書けばいい → すらすらと書ける ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト なぜ「すらすらと書けない」のか (3) 書く内容が決まっているようにみえて、実は決まっていない。 3. 対象読者の認識 (2) 2) 異なる職責（引き継ぎ＋教育） a) 自分→他人 他人がそれを読んである程度理解できるものが必要。 • 自分は分かってるが他人は分からない • 自分もよく分からないから他人に説明できない という場合、調査、学習の上、「思ったまま」＋α（教育）の内容が必要。 ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト なぜ「すらすらと書けない」のか (4) 書く内容が決まっているようにみえて、実は決まっていない。 3. 対象読者の認識 (3) 2) 異なる職責（引き継ぎ＋教育） b) 他人→自分 自分がそれを読んである程度理解できなければいけない。 理解のために何を学習すれば良いか。経緯や背景（理由）は何か。 → それらを探索・調査する手間がかかる。 ※探索・調査対象が現存するとは限らない。 ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト 「すらすらと書く」ためには 逆引きしていくと ドキュメントをどう整備するかの切り分け（新規・更新ともに） • 整備の対象が「表現（体裁）」か「内容」か。 たいてい両方が対象になる。 表現を整えるには内容を理解する必要がある。 • 整備の対象が「構成」か「内容」か。 たいてい両方が対象になる。 構成を整えるには内容を理解する必要がある。 → 共通項は「内容の理解」 ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト 「すらすらと書く」ためには (2) 逆引きしていくと (2) 内容を理解するには自身の教育が必要。 「何を学べばいいか」という自身への教育が必要。 「何を学べばいいか」という調査が必要。 • 経緯、背景、理由 （ローカルな事情や業務内容なども含まれる） • 調査先（人、既存の資料、履歴、etc）の把握 その上で、ツールの理解や適切な利用が必要。 ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト 探索・調査対象が現存するとは限らない にゃーん 「めんどくさい」を完 全に解消することは 難しいので、「めんど くさい」という隠れた コストを認識しつつ、 ねこでもなでましょう。 ※そのドキュメントは 自分が書ける（可 能）のか、という根源 的な問いも課題です。 にゃーん… https://www.photo-ac.com/main/detail/24070342 より ssmonline #23 2022/6/21

ドキュメント整備の隠れたコスト ご静聴ありがとうございました ssmonline #23 2022/6/21