ソフトウェアエンジニアの社内技術ドキュメンテーションへの向き合い方 -実践編-
18.3K Views
February 26, 24
スライド概要
ソフトウェアエンジニアの重要なタスクの 1 つであるドキュメンテーション。
その重要度や難易度の高さにも関わらず、あまり深く議論されることが多くない印象を受ける。
そのため、組織が良質な文書を公開しているかは、それを書くソフトウェアエンジニアの意欲と技量や確保可能な稼働時間に大きく依存する。
ここでは体系的な社内ドキュメンテーションを公開するにあたり、回避不可能な5大トレードオフへの向き合い方と、社内ドキュメンテーションの実践的10の手順を説明する。
某教育系サービスの内製開発にソフトウェアエンジニアとして携わっています。 使用技術スタックは、サーバーサイドは Ruby on Rails、フロントエンドは React.js + TypeScript です。 プライベートでは Python も少し書きます。 学部生時代は英語学を専攻していたので、言語に強い興味を持っています。 私の所属する部署ではテーマフリーの LT 会や技術トーク会があり、そこで利用した資料をこちらにアップしています。 ご興味があれば是非ご覧下さい。
関連スライド
各ページのテキスト
ソフトウェアエンジニアの 社内技術ドキュメンテーションへの 向き合い方 -実践編作成者: 石田 隼人 英語版はこちら 最終更新日: 2024年07月16日 1
自己紹介 • 各種アカウント • • • • • Linkedin: @hayat01sh1da GitHub: @hayat01sh1da Speaker Deck: @hayat01sh1da Docswell: @hayat01sh1da HackMD: @hayat01sh1da • 職業: ソフトウェアエンジニア • 趣味 • • • • • 語学学習 カラオケ 音楽鑑賞 映画鑑賞 卓球 2
免許 / 資格 • 英語 • TOEIC® Listening & Reading 915点: 2019年12月 取得 • エンジニアリング • • • • 情報セキュリティマネジメント: 2017年11月 取得 応用情報技術者: 2017年06月 取得 基本情報技術者: 2016年11月 取得 IT パスポート: 2016年04月 取得 • その他 • 珠算2級: 2002年06月 取得 • 暗算3級: 2001年02月 取得 3
スキルセット • 言語 • 日本語: 母語 • 英語: ビジネスレベル • 開発 • Ruby: 中上級(FW: Ruby on Rails) • Python: 中級 • TypeScript:中級(Library: React.js) • HTML:中級(Library: Bootstrap) • CSS:中級(Library: Bootstrap) • SQL:中級 • その他 • ドキュメンテーション: 上級 4
職歴 1. システムエンジニア @SES • レガシー Windows Server 運用・保守 • 社内アカウント管理 • 社内セキュリティ啓蒙 • 英語通訳(海外拠点とのオンライン会議・ベンダー対応・海外スタッフのアテンド) 2. ソフトウェアエンジニア @受託開発会社 • サーバーサイド開発(Ruby on Rails, RSpec) • フロントエンド開発(HTML / CSS, JavaScript) • QA(Native iOS / Android Apps) • 企業技術ブログ記事執筆 3. ソフトウェアエンジニア @チャットボットプラットフォーム開発会社 • 既存チャットボットプラットフォーム開発・運用・保守(Ruby on Rails, RSpec) • 新規チャットボットエンジン性能検証(Ruby, Ruby on Rails, RSpec, Python) 4. ソフトウェアエンジニア @メガベンチャーの教育系サービス内製開発部門 • 学事・進路支援機能開発(Ruby on Rails, RSpec, Minitest, TypeScript + React.js) • 年次高校マスタデータ更新(Ruby on Rails, RSpec) • ドキュメンテーション執筆・啓蒙活動 5
国際交流活動 • 大学時代 • • • • 英語学ゼミ(マスメディア英語) 国際交流サークル兼部(2年次) 内閣府主催国際交流プログラム(2013年 - 2016年) 日本語学の授業の S 単位取得(最終年次) • 海外生活 • オーストラリアでのワーキングホリデー(2014年04月 - 2015年03月) • • • 2ヶ月間のシドニーの語学学校通学 6ヶ月間の Hamilton Island Resort での就労 1ヶ月間の NSW 州の St Ives High School での日本語教師アシスタントボランティア活動 • その他活動 • • • • • 英語での日々の日記(2014年04月 - 現在) Sunrise Toastmasters Club 参加(2017年02月 - 2018年03月) Vital Japan 参加(2018年01月 - 2019年07月、2022年10月 - 2023年02月) 英語自己学習 オーストラリアの友人とのビデオ通話 6
目次 1. はじめに 2. 回避不可能な5大トレードオフへの向き合い方 3. 社内技術ドキュメンテーションの実践的10の手順 4. まとめ 5. おわりに 6. 参考文献 7
1. はじめに 8
1. はじめに 前作『ソフトウェアエンジニアの社内技術ドキュメンテーションへの向き合い方 -一般論編-』で以下の項目について詳説 した。 1. 社内技術ドキュメンテーションに必須の6大要素 1. 2. 3. 4. 5. 6. 科学的であること 効率的であること 印象的であること 想定読者層が明確であること 技術者と非技術者間のコミュニケーション 適切なワークフロー設計 2. 社内技術ドキュメンテーションに必須の5大スキル 1. 2. 3. 4. 5. 読み手目線の説明能力 ステークホルダーとの協業能力 問題解決能力 コスト管理能力 潜在的な問題の予測能力 3. 体系的社内技術ドキュメンテーションの3大恩恵 1. 組織への信頼感の醸成 2. 中長期的な成果の創出 3. 中長期的なコスト削減 9
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-technical-documentation-for-software-engineers-practices
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p14
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p15
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p16
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p17
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p18
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p19
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p20
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p22
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p23
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p24
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p25
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p26
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p27
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p29
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p30
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p32
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p33
1. はじめに そして、回避不可能な5大トレードオフについて頭出しを行った。 今回は、社内技術ドキュメンテーションにおいて向き合わなければいけな いトレードオフを分析する。 その結果を加味した上で、どのような手順を踏めばソフトウェアエンジ ニ アが社内技術ドキュメンテーションで享受する恩恵を最大化出来るか を考 察する。 今回も前回同様、以下の記事を解釈・分析した内容を元に議論を展開する。 Basics Of Technical Documentation For Engineers, Ayca LITTLE, Published in DatasheetEST by TDSmaker, 25 April 2018 10
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p12
- https://medium.com/datasheetest-by-tdsmaker/basics-of-technical-documentation-for-engineers-36deab8d1220
- https://medium.com/datasheetest-by-tdsmaker?source=post_page-----36deab8d1220--------------------------------
2. 回避不可能な5大トレードオフへの向き合い方 11
2. 回避不可能な5大トレードオフへの向き合い方 ソフトウェアエンジニアが社内技術ドキュメンテーションを行う上で向き 合わなければならない回避不可能な5大トレードオフは以下の通りである。 1. 属人性排除タスクそれ自体の属人性 2. チーム作業の形成すべき合意内容 3. ステークホルダーの数と文書の最新状態追従度の反比例 4. 継続的品質担保責任の発生 5. 投資コストの限界値の見極めの難しさ 12
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p13
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p15
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p17
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p19
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p21
2. 回避不可能な5大トレードオフへの向き合い方 ① 属人性排除タスクそれ自体の属人性 知見や運用が特定のメンバーやチームに依存している状態を属人的である と定義すると、それらをあらゆるステークホルダーが参照・運用出来る状 態にする動きを属人性の排除と呼ぶ。 ドキュメンテーションはそのための手段の1つだが、それが完遂されるまで は作業者が文書化する対象の知見や運用に精通している状態になる。 その知見や運用が比較的軽いものであれば協力者を募りレクチャーするこ とで負荷分散を図ることが出来るが、さもなくば文書化コストをレク チャーコストが上回るため分業体制を敷くことが出来ない。 これこそが属人性排除タスクそれ自体が再帰的に属人的たる理由である。 13
2. 回避不可能な5大トレードオフへの向き合い方 ① 属人性排除タスクそれ自体の属人性 このトレードオフに対する向き合い方は、以下の2つのいずれかである。 1. 文書化コストを受け入れて一気通貫でやり切る 2. レクチャーコストを払ってでも文書化コストを分散させる 私は1を実際に経験し、深遠・難解かつ広範なドメイン知識や情報整理技術 を獲得した一方で、精神的に相当に疲弊してしまった。 「毒を食らわば皿まで」の性分ゆえに1の手法を取ったが、自分ひとりや チームだけで完結することにこだわりがなければ、2の手法を取る方が精神 衛生上大変健全である。 14
2. 回避不可能な5大トレードオフへの向き合い方 ② チーム作業の形成すべき合意内容 チームメンバーで分担して作業する場合、作業負荷は軽減される一方で、 成果物の品質にばらつきが出やすい。 特にチームメンバー間のドキュメンテーションの経験値の差が大きい場合、 文章構成や表現の揺れをレビューで解消し切れないことがある。 デザインガイドラインと同じような発想でドキュメンテーションガイド ラ インを作り縛りを設けるのも一案かもしれない。 しかし、明らかな文法・語法的ミス以外も性悪説モデルで縛り付けると、 今度は書き手の表現の自由を奪い、作業自体の苦痛をもたらしかねない。 15
2. 回避不可能な5大トレードオフへの向き合い方 ② チーム作業の形成すべき合意内容 私が所属するチームでチームドキュメントを作成するにあたりリードを 行った際に、以下の5点に絞って合意形成を行った。 1. 全体の節・章立て 2. 節・章ごとのコスト(ストーリーポイント) 3. 節・章ごとの担当者割振り方針・担当者任用 4. 図解に使用する描画ツール 5. 作業ワークフロー 厳密なルールは設けず、重要な事項のみ合意形成を行うことで、良好な作 業体験と品質の担保を実現した。 16
2. 回避不可能な5大トレードオフへの向き合い方 ③ ステークホルダーの数と文書の最新状態追従度の反比例 個人的な文書は自分の意志だけで文書を改訂することが出来、チームの場 合はメンバー同士の合意さえ形成されていればそれが可能である。 ところが、他部署のメンバーや場合によって社外の人間が関わるような広 範なステークホルダーを擁する大きなプロジェクトの場合、仕様や要件の 変更や更新が多くの人を介した伝言ゲームで伝わることによる正確性とリ アルタイム性の担保の難しさが存在する。 また、変更や更新した情報対する合意を形成するのもまた難しい。 おしなべて、多くのステークホルダー間で最新の情報に関する認識の軌を 一にするのは容易ではない。 17
2. 回避不可能な5大トレードオフへの向き合い方 ③ ステークホルダーの数と文書の最新状態追従度の反比例 このトレードオフに対する向き合い方は、対象のステークホルダーを必要 最小限に絞り、スモールスタートで文書化に着手することだ。 具体的には、まずは所属チーム内で合意形成が完結するレベルのドキュメ ンテーションを行い、文書を参照するステークホルダーが必要とする情報 を徐々に盛り込んでいくスモールステップを踏むのが良い。 ゼロベースでいきなり大きな成果物を作るのは完成品を想像しづらく手戻 りも多いので、具体的なイメージを持ちやすい成果物を小さく作って育て ていくという発想を持つとよい。 18
2. 回避不可能な5大トレードオフへの向き合い方 ④ 継続的品質担保責任の発生 ドキュメンテーションは一度着手したら、文書の品質を一定以上に担保してメ リットを提供続けなければ存在価値がない。 陳腐化して最新の仕様や要件から大きく落後した文書は、享受出来る恩恵がない どころか、混乱をもたらす有害なゴミである。 一度ゴミと化した文書は、放置すると余計な保有コストや情報検索時のノイズを 生み、大きな不利益をもたらす。 その結果、作業に費やしたコストは水泡に帰すばかりでなく、最悪の場合に一か ら作り直しをすると追加のコストまでかかることになる。 そのため、基本的に一度作成した文書は品質を担保し続けなければならない。 余談だが、意識か無意識か上記の内容を理解しているからこそ多くの組織でド キュメンテーションに着手するのに腰が重いのだと推察する。 19
2. 回避不可能な5大トレードオフへの向き合い方 ④ 継続的品質担保責任の発生 このトレードオフに対する向き合い方は、以下の2つの両方である。 1. マネージャーや組織長などのコストに関して権限を持つ上長と担保する 品質とコスト感について合意形成する。 • 社内技術ドキュメンテーションに必須の6大要素は最低限必ず満たすようにする 2. コストから逆算した作業計画を立案して必要であればチームメンバーを 巻き込んだ協業体制を敷く。 • 成果物の要求される品質の担保への最短距離を意識する 3. 管理・運用コストに釣り合う恩恵を享受出来ない場合、その文書はアー カイヴし、改めてその仕様・要件や知見を明文化する価値を再考する。 20
2. 回避不可能な5大トレードオフへの向き合い方 ⑤ 投資コストの限界値の見極めの難しさ 社内技術ドキュメンテーションはそれ自体が利益をもたらすものではない ため、投資した初期コスト以上の還元される成果がどの程度かという ROI の 判断は難しい。 ドキュメンテーションは作業コストの見積りが難しい上、見積りと作業 実 績の乖離が往々にして発生する不確実を孕んでいる。 だからこそ、作業者にはコスト管理能力が求められる訳だ。 このトレードオフへの向き合い方は、経験を個人・チームで積むしかない。 不確実性の見極め能力の獲得には、理論だけではなく実践の積み重ねが 必 要だからだ。 21
3. 社内技術ドキュメンテーションの実践的10の手順 22
3. 社内技術ドキュメンテーションの実践的10の手順 前章の回避不可能な5大トレードオフを加味した上で、社内技術ドキュメンテー ションから享受する恩恵を最大化するために踏むべき具体的な10の手順を説明す る。 1. 5W1H の明確化 2. Ownership とステークホルダーの明確化 3. 文書の置き場と公開場所の検討 4. 文書化対象の情報の洗い出し 5. 文書全体の構成検討 6. 文体・描画ツールの合意形成 7. 節・章ごとの明文化難易度評価 8. 節・章ごとの担当者割り振り 9. レビュー 10.公開 23
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p12
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p24
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p26
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p28
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p30
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p31
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p33
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p34
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p35
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p36
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p37
3. 社内技術ドキュメンテーションの実践的10の手順 ① 5W1H の明確化 社内技術ドキュメンテーションに限らず、全ての作業では以下の 5W1H を 明確にする必要がある。 • WHY: 作業目的。何が問題でそれを解決するとどう嬉しいのか？ • WHAT: 個々の作業。作業目的を果たすために必要なタスクは何か？ • WHO: 作業担当者。 誰が、もしくはどのチームがやるのか？ • WHEN: 開始・終了時期。いつまでに始め、完了させるのか？ • WHERE: 成果物納品先。文書をどこに置き公開するのか？ • HOW: 方法・手順。どのように進めるのか？ 24
3. 社内技術ドキュメンテーションの実践的10の手順 ① 5W1H の明確化 とりわけ WHY(作業目的)を最初に明確にすることは非常に重要である。 文書がないことで何をどう困っていて、それを解決するとどんなメリットがあ る のか、継続的品質担保責任の発生を考慮するとそもそもドキュメンテーショ ンが 最適な手段なのかを検討する必要がある。 ドキュメンテーションの必要性は、以下の2つの質問を自問自答すると分かる。 1. 今この瞬間に自分が事故や病気で死んだら困るステークホルダーがいるか？ 2. 今この瞬間に特定のステークホルダーが事故や病気で死んだら自分が困るか？ いずれかの答えが是であれば「ドキュメンテーションの必要有り」と判定出来る。 (残りの 4H1W は手順2 - 10で説明するので、このまま読み進めて頂きたい) 25
3. 社内技術ドキュメンテーションの実践的10の手順 ② Ownership とステークホルダーの明確化 Ownership はドキュメンテーションのワークフローにおいて、設計・執 筆・ レビュー・公開を管理する責任の所在が誰に、もしくはどのチームに ある かを指す。 これを曖昧にするとたちまち文書は放置され、あっという間に継続的品 質担 保責任が反故にされてしまうので、最初期に明確にする必要がある。 ステークホルダーは、ここでは文書の読み手や情報源となる関係者を指す。 これを明確にすることは、想定読者層と公開範囲の設定してそれを把握す るために必要である。 26
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p31
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p35
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p36
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p20
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p18
- https://speakerdeck.com/hayat01sh1da/science-of-corporate-technical-documentation-for-software-engineers-theories?slide=20
3. 社内技術ドキュメンテーションの実践的10の手順 ② Ownership とステークホルダーの明確化 私が所属する部署では、Ownership はチームドキュメントの場合はチーム単 位で持つ。 一方、年次メンテナンスなど輪番制のプロジェクトでは明確な Ownership が 存在しないので、その年の担当者が持つことになる。 それが原因で長年ドキュメントが存在しなかったので、自ら Ownership を 持って決定版文書を作成した(属人性排除タスクそれ自体の属人性に大い に 悩まされたが)。 どうしても Ownership が明確にならない場合は、(話を理解してくれること を願いながら)上長に相談し方針を一緒に考えて頂くと良いだろう。 27
3. 社内技術ドキュメンテーションの実践的10の手順 ③ 文書の置き場と公開場所の検討 ドキュメンテーションで恐らく一番最初に直面するのが「どこに書こ う？」問題である。 以下のトレードオフを考慮しつつ、ドキュメントツールごとの長所・短所 を比較・検討の上決定する。 • 参照コスト: 文書を読む上でハードルがないか？ • 検索性が低かったり見辛かったり VPN に繋がなければ見れないなど • 参照する行為にストレスを感じるとせっかく書いた文書も読まれなくなる • 編集コスト: 文書を更新する上でハードルはないか？ • 管理・運用しやすいフォーマット(e.g., HTML, Markdown, WYSIWYG) • 精密さを要求される情報の更新はレビューを必須とし、一定の「不便さ」は残す 28
3. 社内技術ドキュメンテーションの実践的10の手順 ③ 文書の置き場と公開場所の検討 前頁のトレードオフを鑑みて、私が所属するチームでは Honkit エンジンを使い、 ドキュメントを AWS S3 上に配置して静的ページとしてホスティングする方式を採 用している。 公開までの手順は以下の 3 つだけである。 1. 専用の GitHub リポジトリ上でトピックブランチを切る。 2. 編集内容をレビューし、main ブランチにマージする。 3. GitHub Actions が AWS S3 上にデプロイを行い自動公開される。 参照コストの観点では、VPN 接続が不要で文書は Wiki 形式で構成はサイドメ ニューにツリー構造で表示されるため、検索性が高く見やすいのが長所だ。 編集コストの観点では、レビュー必須の運用によって編集した情報は第三者の目 を通すことになっているので、情報の正確さと信用性も担保されているのが長所 だ。 29
3. 社内技術ドキュメンテーションの実践的10の手順 ④ 文書化対象の情報の洗い出し 5W1H の明確化の話に若干戻るが、情報が明文化されていないことで困って いるからこそドキュメンテーションをしようとしているはずである。 SaaS の開発に携わっているソフトウェアエンジニアなら、例えば以下のよ うな情報が欲しいはずだ。 • インフラ構成図 • マイクロサービス間通信シーケンス図 • DB のテーブル構成と E-R 図 • 外部システム連携図 • 運用・トラブルシューティング 30
3. 社内技術ドキュメンテーションの実践的10の手順 ⑤ 文書全体の構成検討 洗い出した欲しい情報を粒度や重要度の降順(大/高 → 小/低)で並べ替え、例 えば以下のような節と章に切り出す。 1. 全体構成 1. インフラ構成 2. マイクロサービス間通信 2. DB 周辺知識 1. テーブル構成 2. E-R 図 3. … 31
3. 社内技術ドキュメンテーションの実践的10の手順 ⑤ 文書全体の構成検討 ドキュメンテーションは品質を求めると青天井なので、前頁のようにまず は大まかで良いので全体の構成を決めてしまい、内容を縛るのが効率の良 い進め方である。 内容を詰めていくうちに構成と整合性が取れない場合は、表題を変えたり 節や章を切り直すのもよくあることだ。 一度決めたからと言ってその構成を未来永劫守らなければいけない訳では ない。 むしろ、構成 ⇆ 内容間の最適化が発生するのが普通なので、途中で構成が 変わることはおかしいと案ずる必要はない。 32
3. 社内技術ドキュメンテーションの実践的10の手順 ⑥ 文体・描画ツールの合意形成 個人で作業する場合は問題ないが、とりわけチームメンバーで分担する場合に揺 れが発生するのが文体や使用する描画ツールだ。 文体に関しては、想定読者層が既存参画メンバーだけなら常体(である調)、新規参 画者や広範なステークホルダーの場合は敬体(です・ます調)を採用する。 描画ツールに関しては、少なくとも作業者が退職しても閲覧権限が失われない状 態を担保しなければならない。 例えば、Google Drive に保存した画像を埋め込んでいる場合、退職後はアカウント が削除されて参照エラーになってしまう。 私が所属するチームでは、Mermaid や PlantUML など Plain Text ベースで描画出来る エンジンも検討したが、表現力や Honkit との親和性を考慮し draw.io を採用した。 描画した図表は SVG ファイルとして保存して Markdown ファイルから参照し、 GitHub でバージョン管理を行っている。 33
3. 社内技術ドキュメンテーションの実践的10の手順 ⑦ 節・章ごとの明文化難易度評価 文書を構成する節・章には必ず概念的抽象度に差があり、明文化する上で の難易度・作業コストと正比例する。 私が所属するチームでは図解が必要かどうかの尺度で概念的抽象度を評価 し、以下の3つの分類でストーリーポイントを付けていった。 • [MUST] 図解がなければ理解に支障が出るほど概念的抽象度が高い: 3 - 5 • [SHOULD] 文章で概ね理解出来るが図解がないと認知負荷が高い: 2 - 3 • [MAY] 図解の有無による理解度への影響がない: 1 - 2 上記のストーリーポイントとチームのベロシティを照らし合わせ、そのス プリントでどの程度タスクを消化するかを決定した。 34
3. 社内技術ドキュメンテーションの実践的10の手順 ⑧ 節・章ごとの担当者割り振り 精通している節・章をそのメンバーが担当するのが最も効率的だが、作業 負荷が集中する可能性がある。 一方で、作業を均等に分担すると、精通していない分野の節・章を担当 するメンバーには調査・執筆コストがかかる。 私が所属するチームは最初は前者の方針で進めたが、手の早いメンバー がどんどん作業を巻き取っていき、最終的に後者の方針にスイッチした。 精通していない分野の明文化は確かに大変ではあったが、あるメンバー は別チームの有識者に熱心なヒアリングを行うことでこの難局を乗り 切った。 そのメンバーは有識者とのコミュニケーションや新しい知見の獲得を楽 しんだようで、精通していない分野のドキュメンテーションはポジティ ヴな体験をもたらすことすらある。 35
3. 社内技術ドキュメンテーションの実践的10の手順 ⑨ レビュー 社内技術ドキュメンテーションのワークフローに則り、読み手目線で設計 と内容を精査し、不自由さをフィードバックするのがこの段階である。 具 体的には、以下の観点を持ち、その上で不便さがあれば適宜フィード バックすると良い。 • 科学的であるか • 効率的であるか • 印象的であるか • 想定読者層が明確であるか 36
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p20
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p31
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p15
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p16
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p17
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p18
3. 社内技術ドキュメンテーションの実践的10の手順 ⑩ 公開 レビューをクリアしたら、然るべきフローで文書を公開する。 公開した文書はステークホルダーに情報をインプットしてもらうことが 目 的なので、参照してもらえなければ意味がない。 公開後は然るべきステークホルダーに広報し、文書の存在を知ってもら い フィードバックを積極的に得て品質向上に役立てていく。 あとは Ownership を持つメンバーやチームが責任を持って文書を運用してい けば、 体系的社内技術ドキュメンテーションの3大恩恵を享受し続けられる だろう。 37
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p36
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p20
- https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p29
4. まとめ 38
4. まとめ 1. 回避不可能な5大トレードオフへの向き合い方 1. 属人性排除タスクそれ自体の属人性 2. チーム作業の形成すべき合意内容 3. ステークホルダーの数と文書の最新状態追従度の反比例 4. 継続的品質担保責任の発生 5. 投資コストの限界値の見極めの難しさ 2. 社内技術ドキュメンテーションの実践的10の手順 1. 5W1H の明確化 2. Ownership とステークホルダーの明確化 3. 文書の置き場と公開場所の検討 4. 文書化対象の情報の洗い出し 5. 文書全体の構成検討 6. 文体・描画ツールの合意形成 7. 節・章ごとの明文化難易度評価 8. 節・章ごとの担当者割り振り 9. レビュー 10.公開 39
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p12
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p13
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p15
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p17
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p19
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p21
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p23
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p24
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p26
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p28
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p30
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p31
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p33
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p34
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p35
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p36
- https://www.docswell.com/s/hayat01sh1da/KRXJ9J-science-of-corporate-technical-documentation-for-software-engineers-practices#p37
5. おわりに 40
5. おわりに 社内技術ドキュメンテーションはその重要度と難易度に見合った評価を 得 辛い作業という印象がある。 私自身、エンジニア界隈ではドキュメンテーションよりコードを書くの が 正義という伝統と文化がある印象を持っている。 確かにコードは最新の仕様や要件に則って書かれたものが多いので、そ れ を読めば良いという意見も一理ある。 しかし、「技術者と非技術者間のコミュニケーション」でも述べたように、 技術者だけで完結する仕事は実際は多くなく、非技術者に分かるように言 語化する能力はソフトウェアエンジニアに必須である。 幸い私が所属する部署は比較的ドキュメンテーション文化が根付いており、 適切に評価されるし言語化能力の高いメンバーも多い。 41
5. おわりに これまで4社経験してきたが(2024年02月現在)、その中で出会ったドキュ メ ンテーション習慣のあるエンジニアの共通点は未来の自分の記憶を信 用し ていないことである。 ソースコードは1ヶ月も経てばほぼ他人が書いたものなので、どんな背景 で その実装をしたのか、またはレビュアーとして承認したのかを詳らかに 覚 えていることはほとんどないと言って良い。 そんな時に詳細に残しておいた作業ログを見れば背景を思い出すことが出 来てるので、過去の自分に感謝するものだ。 ドキュメンテーションは一定のスキルが要求されるが、それ以上に未来 の 自分と他人を思いやって記録を残す行為の延長に過ぎないと考える。 ドキュメンテーションに苦手意識のあるソフトウェアエンジニアの方々は、 まずは本日の作業ログを残すところから始めてみてはどうだろう。 それがいつか重要な社内技術ドキュメンテーションをする場面で必ず役 に 立つはずだ。 42
6. 参考文献 43
6. 参考文献 • Basics Of Technical Documentation For Engineers • 最終アクセス日: 2023年11月12日 • Dictionary.com • 最終アクセス日: 2023年11月12日 • 英辞郎 Pro Lite • 最終アクセス日: 2023年11月12日 • [PBI] 技術仕様ドキュメント作成 • 私が所属する部署社員のみ閲覧可 • [SBI][技術仕様ドキュメント] 7. 社外システム連携 • 私が所属する部署社員のみ閲覧可 44
EOD 45