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

23.7K Views

February 21, 24

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

スライド概要

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

profile-image
スライド一覧

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

シェア

またはPlayer版

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

（ダウンロード不可）

関連スライド

slide-thumbnail

ソフトウェアエンジニアの社内技術ドキュメンテーションへの向き合い方 -実践編-
仕事 エンジニアリング ドキュメンテーション ソフトウェアエンジニアの社内ドキュメンテーションへの向き合い方
user-img 石田 隼人 18.3K
slide-thumbnail

チームビルディングと雑談会 -「心理的安全性」とは？-
仕事 スクラム開発 チームビルディング 心理的安全性 雑談 チームビルディングと雑談会 -「心理的安全性」とは？-
user-img 石田 隼人 4.2K
slide-thumbnail

現代英語を知ろう Vol.3 -英語の語彙①(複合語・派生語・借用語)-
自然言語 言語学 英語学 現代英語を知ろう
user-img 石田 隼人 3.7K
slide-thumbnail

厳選！ドラゴンボール七不思議
サブカルチャー 漫画 アニメ ドラゴンボール
user-img 石田 隼人 2.8K
slide-thumbnail

日本語を知ろう -格助詞「で」-
自然言語 言語学 日本語学 日本語を知ろう
user-img 石田 隼人 2.4K
slide-thumbnail

現代英語を知ろう Vol.1 -英語という言語-
自然言語 言語学 英語学 現代英語を知ろう
user-img 石田 隼人 2.3K
各ページのテキスト
1.

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

2.

自己紹介 • 各種アカウント • • • • • Linkedin: @hayat01sh1da GitHub: @hayat01sh1da Speaker Deck: @hayat01sh1da Docswell: @hayat01sh1da HackMD: @hayat01sh1da • 職業: ソフトウェアエンジニア • 趣味 • • • • • 語学学習 カラオケ 音楽鑑賞 映画鑑賞 卓球 2

3.

免許 / 資格 • 英語 • TOEIC® Listening & Reading 915点: 2019年12月 取得 • エンジニアリング • • • • 情報セキュリティマネジメント: 2017年11月 取得 応用情報技術者: 2017年06月 取得 基本情報技術者: 2016年11月 取得 IT パスポート: 2016年04月 取得 • その他 • 珠算2級: 2002年06月 取得 • 暗算3級: 2001年02月 取得 3

4.

スキルセット • 言語 • 日本語: 母語 • 英語: ビジネスレベル • 開発 • Ruby: 中上級(FW: Ruby on Rails) • Python: 中級 • TypeScript:中級(Library: React.js) • HTML:中級(Library: Bootstrap) • CSS:中級(Library: Bootstrap) • SQL:中級 • その他 • ドキュメンテーション: 上級 4

5.

職歴 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

6.

国際交流活動 • 大学時代 • • • • 英語学ゼミ(マスメディア英語) 国際交流サークル兼部(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

7.

目次 1. はじめに 2. ドキュメンテーションとは？ 3. 社内技術ドキュメンテーションに必須の6大要素 4. 社内技術ドキュメンテーション執筆に必須の5大スキル 5. 体系的社内技術ドキュメンテーションの3大恩恵 6. 回避不可能な5大トレードオフ 7. まとめ 8. 参考文献 7

8.

1. はじめに 8

9.

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

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

25.

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

26.

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

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