ソフトウェアエンジニアの社内技術ドキュメンテーションへの向き合い方 -一般論編-

23.7K Views

February 21, 24

#仕事 #エンジニアリング #ドキュメンテーション #ソフトウェアエンジニアの社内ドキュメンテーションへの向き合い方 #ソフトウェアエンジニアリング #技術ドキュメンテーション #ドキュメント作成 #知識共有 #生産性向上

スライド概要

ソフトウェアエンジニアの重要なタスクの1つであるドキュメンテーション。
その重要度や難易度の高さにも関わらず、あまり深く議論されることが多くない印象を受ける。
そのため、組織が良質な文書を公開しているかは、それを書くソフトウェアエンジニアの意欲と技量や確保可能な稼働時間に大きく依存する。
ここでは体系的な社内ドキュメンテーションに必須の6大要素と5大スキル、享受出来る3大メリットについての一般論を説明する。

石田隼人

@hayat01sh1da

スライド一覧

某教育系サービスの内製開発にソフトウェアエンジニアとして携わっています。使用技術スタックは、サーバーサイドは Ruby on Rails、フロントエンドは React.js + TypeScript です。プライベートでは Python も少し書きます。学部生時代は英語学を専攻していたので、言語に強い興味を持っています。私の所属する部署ではテーマフリーの LT 会や技術トーク会があり、そこで利用した資料をこちらにアップしています。ご興味があれば是非ご覧下さい。

またはPlayer版

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

（ダウンロード不可）

関連スライド

ソフトウェアエンジニアの社内技術ドキュメンテーションへの向き合い方 -実践編-

仕事エンジニアリングドキュメンテーションソフトウェアエンジニアの社内ドキュメンテーションへの向き合い方

石田隼人 18.2K

チームビルディングと雑談会 -「心理的安全性」とは？-

仕事スクラム開発チームビルディング心理的安全性雑談チームビルディングと雑談会 -「心理的安全性」とは？-

石田隼人 3.9K

現代英語を知ろう Vol.3 -英語の語彙①(複合語・派生語・借用語)-

自然言語言語学英語学現代英語を知ろう

石田隼人 3.7K

厳選！ドラゴンボール七不思議

サブカルチャー漫画アニメドラゴンボール

石田隼人 2.7K

日本語を知ろう -格助詞「で」-

自然言語言語学日本語学日本語を知ろう

石田隼人 2.4K

Economy of Efforts -労力の節約原理-

自然言語言語学英語学日本語学 economy of effort -労力の節約原理-

石田隼人 2.2K

各ページのテキスト

ソフトウェアエンジニアの社内技術ドキュメンテーションへの向き合い方 -一般論編作成者: 石田隼人英語版はこちら最終更新日: 2024年07月16日 1

https://speakerdeck.com/hayat01sh1da/science-of-corporate-technical-documentation-for-software-engineers-theories

自己紹介 • 各種アカウント • • • • • 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. ドキュメンテーションとは？ 3. 社内技術ドキュメンテーションに必須の6大要素 4. 社内技術ドキュメンテーション執筆に必須の5大スキル 5. 体系的社内技術ドキュメンテーションの3大恩恵 6. 回避不可能な5大トレードオフ 7. まとめ 8. 参考文献 7

1. はじめに 8

1. はじめに社内技術ドキュメンテーションは内製・受託・客先常駐など形態に関わらず、開発や仕様把握を円滑に行うために不可欠な文書である。私自身、これまでソフトウェアエンジニアとしてプロジェクト運営に必要なドキュメントの設計・執筆・公開や、チーム開発に必要なドメイン知識の明文化のリード、広域なステークホルダー向けの文書作成を行ってきた。それらの経験を通して自身の中に社内技術ドキュメンテーションの知見が一定以上蓄積されたので、その知見を整理・体系化し共有したい。 9

10.

1. はじめにただし、自身の限られた経験で得た管見では主観的・恣意的な知見の共有になってしまう。そこで、この機会に改めて一般論をインプットする意図で以下の記事の解釈・考察を行った。 Basics Of Technical Documentation For Engineers, Ayca LITTLE, Published in DatasheetEST by TDSmaker, 25 April 2018 基本的にマーケティング観点で書かれた記事ではあるが、「顧客 → 組織内のステークホルダー」という具合に視点を切り替えると、十分社内技術ドキュメンテーションの一般論として通用するので文献として採用した。 10

11.

2. ドキュメンテーションとは？ 11

12.

2. ドキュメンテーションとは？ドキュメンテーションとは、文書という媒体を通じて情報を読み手に伝える行為や執筆された文書そのものを意味する。換言すると、ドキュメンテーションはコミュニケーション手段の1つである。基本的に書き手→ 読み手の一方通行のコミュニケーションなので、書き手は文書の内容に 100% の責任を負う。社内技術ドキュメンテーションにおいては、読み手はチームやプロジェクトなど、社内組織の参画者などを含めた利害関係者(ステークホルダー)を指す。文書はステークホルダーが書き手の伝えたい情報を得るための最重要インターフェースであり、この品質と組織内のステークホルダーのコミット度合(高い生産性や意欲の維持)の間には高い相関関係がある。 12

13.

3. 社内技術ドキュメンテーションに必須の6大要素 13

14.

3. 社内技術ドキュメンテーションに必須の6大要素書き手と読み手のインターフェースとなる文書の品質を担保するためには、以下の6つの要素が必要不可欠である。 1. 科学的であること 2. 効率的であること 3. 印象的であること 4. 想定読者層が明確であること 5. 技術者と非技術者間のコミュニケーション 6. 適切なワークフロー設計 14

15.

3. 社内技術ドキュメンテーションに必須の6大要素 ① 科学的であること文書が科学的であるために必須の要素は以下の3つである。 1. 一貫性: いつ、どこ、誰が読んでも再現性があること • → 外部要因に左右されないこと 2. 精度: 事実と乖離のない情報が参照出来ること • → 掲載内容には必ず論拠が存在すること 3. 関連性: 必要な情報が網羅されていて抜け漏れがないこと • → 特に作業目的のような本質的な内容が必ず掲載されていること文書を通して必要な事実に基づいた情報が過不足なく共有され、その内容に冪等性があることが「科学的である」ための条件である。 15

16.

3. 社内技術ドキュメンテーションに必須の6大要素 ② 効率的であること例え文書が科学的であっても、それが散在していては必要な情報を探すのに骨が折れてしまう。適切な索引を張り、必要な情報がどこにあるかが一目で分かるように整理・分類する。情報を適切に集約・体系化することで、最小の労力で必要な情報が過不足なく手に入る状態を担保することは必要不可欠である。 16

https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p15

17.

3. 社内技術ドキュメンテーションに必須の6大要素 ③ 印象的であること文書が科学的・効率的であっても、その内容が読了後読み手の印象や記憶に残っていなければ意味がない。印象に残らない文書は往々にして退屈で読み辛く、視覚情報(e.g., シーケンス図・クラス図・ER 図)が欠落している。我々が何かを印象強く記憶する時、そこには必ず人間に生来備わった喜怒哀楽の感情が絡む。剰え、我々は最終的な意思決定を理論より感情によって行うことが多い。それだけ読み手の感情に訴えかけることが重要であり、読み手を退屈させない文体・表現・視覚情報やユーモアを織り交ぜるなどの工夫が必要だ。 17

18.

3. 社内技術ドキュメンテーションに必須の6大要素 ④ 想定読者層が明確であること万人が0から100まで理解出来る文書を作成することは現実的には不可能である(全人類が美味しいと唸る料理を発明するくらい難しい)。その前提を踏まえ、予め一定以上の技術・ドメイン知識を有していることを前提に、例えば以下のように読者層を限定することが必要となる。 • 技術者のみの場合: 内容は技術的に詳細かつ網羅的であることを優先する • どの程度の技術・ドメイン知識を必要とするかの前提は必要 • 非技術者も含む場合: 簡潔さ・分かりやすさを優先する • 技術的に詳細過ぎると却って混乱を生む 18

19.

3. 社内技術ドキュメンテーションに必須の6大要素 ⑤ 技術者と非技術者間のコミュニケーション技術的なドキュメンテーションを行うにおいて、技術者だけで完結することは思いの外少ない。何故ならば、技術は何か仕様や要件= エンドユーザーやステークホルダーが必要としていることを実現するために活用されるからである。満たすべき仕様や要件はエンドユーザーに近い位置にいる非技術者がより正確に把握している。その逆もまた然りで、仕様や要件を満たす上での技術的現実性や制約は技術者がより正確に理解している。意思疎通の礎を組織内に確立することや、二者間で密な情報共有を行うことは、高品質な社内技術ドキュメンテーションの必須要件である。 19

20.

3. 社内技術ドキュメンテーションに必須の6大要素 ⑥ 適切なワークフロー設計公開対象の文書が対外的であろうと対内的であろうと、個人が勝手に作業を進めて良いものではない。必ず適切なワークフローに則って設計・執筆・レビューを行い、権限を持ったメンバーが然るべき公開範囲に公開することが必須要件である。 • 設計: 読み手が必要とする情報が検索性高く明文化される構造にする • 執筆: 読み手目線で情報が分かりやすく過不足なく明文化する • レビュー: 読み手目線で設計と内容を精査し、不自由さをフィードバックする • 公開範囲: 情報を共有して然るべきステークホルダーにのみ情報を公開する • 権限管理: 上記の全てのフェーズに対する責任を負うメンバーを任用する • Ownership とほぼ同義。この帰属先を個人ではなくチームにして負荷分散する方が中長期的な運用観点では有効である。 20

21.

4. 社内技術ドキュメンテーション執筆に必須の5大スキル 21

22.

4. 社内技術ドキュメンテーション執筆に必須の5大スキル書き手と読み手のインターフェースとなる文書の品質を担保するためには、以下の5つのスキルが必要不可欠である。 1. 読み手目線の説明能力 2. ステークホルダーとの協業能力 3. 問題解決能力 4. コスト管理能力 5. 潜在的な問題の予測能力 22

23.

4. 社内技術ドキュメンテーション執筆に必須の5大スキル ① 読み手目線の説明能力技術・ドメイン知識は、往々にして抽象度が高く明確な言語化が難しいことが多い。その複雑な問題を、読み手が具体的なイメージを持ちやすいように表現する能力が必要だ。書き手は明文化する内容を十二分に理解することが大前提であり、その上で読み手に伝わるベストな表現方法を採択する判断能力が要求される。つまり、複雑な内容を複雑なまま伝えるのではなく、それをいかに科学的・効率的・印象的に伝えられるかが必須要件である。 23

24.

4. 社内技術ドキュメンテーション執筆に必須の5大スキル ② ステークホルダーとの協業能力技術者と非技術者間のコミュニケーションを元に異なる職種・組織間で情報を適切に共有し、文書を最新状態に保つことは重要である。また、社内技術ドキュメンテーションのステークホルダー間で活発なコミュニケーションを取ることは、文書の品質担保のみならず、意欲と生産性の維持・向上の観点でも非常に有効である。反対に、社内技術ドキュメンテーションのステークホルダー間のコミュニケーションが乏しいと意欲や生産性の停滞・低下に繋がり、最終的に文書の品質を落とすこともある。 24

https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p19

25.

4. 社内技術ドキュメンテーション執筆に必須の5大スキル ③ 問題解決能力技術者と非技術者間のコミュニケーションは重要とはいえ、技術者は自力で問題を解決することが求められることが多く、その問題がどこから発生しているのかを理解して解決策を提示することが出来なければならない。むしろ、自立した問題解決能力を有しているからこそ、不足している情報とそれを取得するためのコミュニケーションパスの把握が出来る。逆に言えば、必要な知識・技術・手順・コミュニケーションを理解し上手く文書に落とし込むことが出来ない場合は、どこかで問題解決能力が不足しているとも言える。 25

https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p19

26.

4. 社内技術ドキュメンテーション執筆に必須の5大スキル ④ コスト管理能力社内技術ドキュメンテーションに必須の6大要素を満たす上で必要なヒト・モノ・カネなどの人的・物的資源がどのくらい必要か、またブロッカーの存在の有無やそれを駆逐するためのコストやリスクを適切に把握・管理することが必須要件である。ドキュメンテーションはどんなに入念に設計をしたとしても、実際に着手すると不確実性を多分に含んでいるため、当初の計画通りに作業を完了させることが難しいことが多い。しかし、それでも予定と実績の乖離とその要因を把握・分析し、同じ轍を踏まないように次回への教訓にすることには少なからず意義がある。 26

https://www.docswell.com/s/hayat01sh1da/5M12VG-science-of-corporate-technical-documentation-for-software-engineers-theories#p14

27.

4. 社内技術ドキュメンテーション執筆に必須の5大スキル ⑤ 潜在的な問題の予測能力ドキュメンテーションの対象となる技術・ドメイン知識は変化し続ける要素が多く、完成した文書はある時点のスナップショットに過ぎない。よって、文書は継続的に更新が行われる必要があるが、何か変更があるたびに行うのは人的・物的コストがかかる。そこで、執筆時点で予見出来る変更は前もって文書に盛り込んでおくか、セクションを切った上でプレースホルダー(e.g., TBA, TBD)を設け、詳細が判明した後で明文化しておくと効率が良い。 27

28.

5. 体系的社内技術ドキュメンテーションの3大恩恵 28

29.

5. 体系的社内技術ドキュメンテーションの3大恩恵ここまでやや抽象的な「べき論」を述べてきたが、体系的な社内技術ドキュメンテーションにはどんなメリットがあるのか。その回答としては、大きく以下の3つの恩恵を享受出来ることが言える。 1. 組織への信頼感の醸成 2. 中長期的な成果の創出 3. 中長期的なコスト削減 29

30.

5. 体系的社内技術ドキュメンテーションの3大恩恵 ① 組織への信頼感の醸成チームやプロジェクトでオンボーディングやその後の仕事に必要な情報が科学的・効率的・印象的な状態で集約・体系化されていることは組織運営において不可欠である。現状の仕様や運用に追従した最新の文書があるのとそうでないのとでは、参画者の心理的負担が大きく異なるからだ。例えば、自分が参画したチームやプロジェクトで進め方が分からない作業を任された時、必要な情報が掲載された文書の有無を訊いても「無い」の一点張りで、剰え「自分でどうにかしろ」と言われたらどうだろう。このような放置プレーの状況で悪戦苦闘されているソフトウェアエンジニアの方々も現実にいらっしゃると思うが、調査コストもストレスも計り知れないほど高いのは想像に難くない。 30

31.

5. 体系的社内技術ドキュメンテーションの3大恩恵 ① 組織への信頼感の醸成反対に、必要な情報が現状の仕様や運用に追従した最新の状態で文書化されており、不明事項に遭遇した時のフォールバック先があると分かってれば、精神的なコンディションは大きく違ってくる。また、文書の存在や品質はその組織の体質を如実に映す鑑であり、それが担保されている組織は中長期的に属人性や負債を残さない取り組みを行っている証であり、参画者は信頼を置く。参画者は意識・無意識に関わらず、体系的社内技術ドキュメンテーションによってその組織を評価し、信頼する。 31

32.

5. 体系的社内技術ドキュメンテーションの3大恩恵 ② 中長期的な成果の創出体系的なドキュメンテーションを行うことは、短期的には高コストに思えるかも知れない。しかし、結果として参画者が素早い情報のキャッチアップを行い、より高次元の仕事をこなして意欲・生産性を向上出来れば、それは近い将来組織に成果として還元される。その観点では、もし今現在文書が存在しなければ、体系的なドキュメンテーションの実施は払うべき必要な初期コストである。反対に、この初期コストを渋ると、参画者は情報のキャッチアップに腐心し、結果的に組織に成果を還元する以前の段階でいつまでも燻り続けることになる。 32

33.

5. 体系的社内技術ドキュメンテーションの3大恩恵 ③ 中長期的なコスト削減体系的社内技術ドキュメンテーションを導線を含めて整備さえしてしまえば、ステークホルダーは公開された文書を継続的に参照することになる。ステークホルダーから頻繁に受ける同じ問いには、人の手を介さずに冪等性を持って何度でも同じ答えを返すことが出来る。その結果、問合せごとに割く人員もお金も不要になるため、属人性の排除とコスト削減が期待出来る。この観点においても、もし今現在文書が存在しなければ体系的なドキュメンテーションは払うべき必要な初期コストであり、中長期的には投資した初期コスト以上の恩恵を享受出来る。 33

34.

6. 回避不可能な5大トレードオフ 34

35.

6. 回避不可能な5大トレードオフ今回は「ソフトウェアエンジニアの社内技術ドキュメンテーションへの向き合い方」の一般論について説明した。しかし、ここまで説明した一般論は言ってみれば理想論であり、実現するにはブロッカーとなるトレードオフが必ず存在する。社内技術ドキュメンテーションには、少なくとも以下の5つのトレードオフが存在する。 1. 属人性排除タスクそれ自体の属人性 2. チーム作業の形成すべき合意内容 3. ステークホルダーの数と文書の最新状態追従度の反比例 4. 継続的品質担保責任の発生 5. 投資コストの限界値の見極めの難しさ上記のトレードオフについては次作『ソフトウェアエンジニアの社内技術ドキュメンテーションへの向き合い方-実践編-』にて考察する。 35

36.

7. まとめ 36

37.

7. まとめ 1. 社内技術ドキュメンテーションに必須の6大要素 1. 科学的であること 2. 効率的であること 3. 印象的であること 4. 想定読者層が明確であること 5. 技術者と非技術者間のコミュニケーション 6. 適切なワークフロー設計 2. 社内技術ドキュメンテーションに必須の5大スキル 1. 読み手目線の説明能力 2. ステークホルダーとの協業能力 3. 問題解決能力 4. コスト管理能力 5. 潜在的な問題の予測能力 3. 系的社内技術ドキュメンテーションの3大恩恵 1. 組織への信頼感の醸成 2. 中長期的な成果の創出 3. 中長期的なコスト削減 37

38.

8. 参考文献 38

39.

8. 参考文献 • Basics Of Technical Documentation For Engineers • 最終アクセス日: 2023年11月12日 • Dictionary.com • 最終アクセス日: 2023年11月12日 • 英辞郎Pro Lite • 最終アクセス日: 2023年11月12日 39

40.

EOD 40