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

1.1K Views

June 21, 22

スライド概要

ssmonline #23 LT登壇資料

profile-image

ソフトウェア技術者 / インフラ技術者 / セキュリティ技術者

シェア

埋め込む »CMSなどでJSが使えない場合

各ページのテキスト
1.

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

2.

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

3.

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

4.

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

5.

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

6.

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

7.

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

8.

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

9.

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

10.

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

11.

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

12.

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

13.

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

14.

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