Tweet
Tweet

Slide 1

Slide 1 text

ドキュメントとの 付き合い方を考える レバテック開発部 内藤 翔太

Slide 2

Slide 2 text

|　© 2024 Levtech Co., Ltd. 2 レバテック開発部 ITSプロダクト開発グループ / 契約請求ドメインチーム 内藤 翔太 SHOTA NAITO ・2023年04月　レバレジーズ株式会社に新卒入社 ・2023年11月　レバテック開発部に異動 ・直近は、システムのリプレースに取り組んでいます！

Slide 3

Slide 3 text

|　© 2024 Levtech Co., Ltd. 3 ● はじめに ● これまでの経験 ● ドキュメントって本当に必要？ ● ドキュメントの品質を上げるためには？ ● まとめ アジェンダ

Slide 4

Slide 4 text

|　© 2024 Levtech Co., Ltd. 4 ● はじめに ● これまでの経験 ● ドキュメントって本当に必要？ ● ドキュメントの品質を上げるためには？ ● まとめ アジェンダ

Slide 5

Slide 5 text

|　© 2024 Levtech Co., Ltd. 5 今日伝えたいこと 組織のパフォーマンスを上げるためには ドキュメントとその品質が欠かせない

Slide 6

Slide 6 text

|　© 2024 Levtech Co., Ltd. 6 突然ですが...

Slide 7

Slide 7 text

|　© 2024 Levtech Co., Ltd. 7 皆さんはドキュメント書いてますか？

Slide 8

Slide 8 text

|　© 2024 Levtech Co., Ltd. 8 僕は書いてます

Slide 9

Slide 9 text

|　© 2024 Levtech Co., Ltd. 9 僕は書いてます というより書くようになりました！

Slide 10

Slide 10 text

|　© 2024 Levtech Co., Ltd. 10 僕は書いてます というより 書くようになりました 書くようになった背景を説明するために、少しこれまでの経験を...

Slide 11

Slide 11 text

|　© 2024 Levtech Co., Ltd. 11 ● はじめに ● これまでの経験 ● どんなドキュメントを書いてる？ ● ドキュメントの品質を上げるためには？ ● まとめ アジェンダ

Slide 12

Slide 12 text

|　© 2024 Levtech Co., Ltd. 12 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09

Slide 13

Slide 13 text

|　© 2024 Levtech Co., Ltd. 13 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09

Slide 14

Slide 14 text

|　© 2024 Levtech Co., Ltd. 14 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09 0→1での経験が多かった どんどん開発を進めてアウトカムを出していこう！ ドキュメントのモチベーションは低め...

Slide 15

Slide 15 text

|　© 2024 Levtech Co., Ltd. 15 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09

Slide 16

Slide 16 text

|　© 2024 Levtech Co., Ltd. 16 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09 システム構成がどうなってるのかパッと分からない... なぜこの設計にしてるの...？ 問い合わせが来たけど、仕様書がないからコード読むしかない...

Slide 17

Slide 17 text

|　© 2024 Levtech Co., Ltd. 17 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09

Slide 18

Slide 18 text

|　© 2024 Levtech Co., Ltd. 18 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09 運用負荷を軽減するためのドキュメント は絶対残そう！！ ex) システム構成図, ADR, 機能仕様書, etc.

Slide 19

Slide 19 text

|　© 2024 Levtech Co., Ltd. 19 僕は書いてます というより 書くようになりました と思いつつも、ドキュメントは本当に必要なのかを問い直してみる

Slide 20

Slide 20 text

|　© 2024 Levtech Co., Ltd. 20 ● はじめに ● これまでの経験 ● ドキュメントって本当に必要？ ● ドキュメントの品質を上げるためには？ ● まとめ アジェンダ

Slide 21

Slide 21 text

|　© 2024 Levtech Co., Ltd. 21 DORA（DevOps Research and Assessment）に学ぶ ドキュメントって本当に必要？ https://dora.dev/capabilities/documentation-quality/

Slide 22

Slide 22 text

|　© 2024 Levtech Co., Ltd. 22 DORA（DevOps Research and Assessment）に学ぶ ドキュメントって本当に必要？ やはりドキュメントは必要で、特にその品質が重要 https://dora.dev/capabilities/documentation-quality/

Slide 23

Slide 23 text

|　© 2024 Levtech Co., Ltd. 23 ● はじめに ● これまでの経験 ● ドキュメントって本当に必要？ ● ドキュメントの品質を上げるためには？ ● まとめ アジェンダ

Slide 24

Slide 24 text

|　© 2024 Levtech Co., Ltd. 24 ドキュメントの品質を上げるためには？ 自チームでは、Diátaxis × Github で管理している Github Diátaxis 他にも ・Google Document（SpreadSheet） ・Datadog のドキュメントが存在するが、 リプレースの文脈で作成した開発関連の ドキュメントは Github から追えるように = 検索の I/F は Github に集約したい！ + 検索機能の検索性も特に問題なし ・Tutorials ・How-to Guides ・Explanation ・Reference の 4 象限でドキュメントを管理するこ とで、目的に応じた情報を簡単に 見つけられるように！ + ドキュメント作成場所も明確に 検索性を高める

Slide 25

Slide 25 text

|　© 2024 Levtech Co., Ltd. 25 目的や達成できることを冒頭に記載する ドキュメントの品質を上げるためには？ 参考: エンジニアのためのドキュメントライティング ユーザは F パターンでドキュメントを読む → 冒頭の数行にユーザが欲しい情報を持ってくる

Slide 26

Slide 26 text

|　© 2024 Levtech Co., Ltd. 26 ビックワードを避ける ドキュメントの品質を上げるためには？ Q. 新システムで現行システムのセッションストアからセッション情報を読み込むと？

Slide 27

Slide 27 text

|　© 2024 Levtech Co., Ltd. 27 ビックワードを避ける ドキュメントの品質を上げるためには？ Q. 新システムで現行システムのセッションストアからセッション情報を読み込むと？ A. 新システムのセッション管理が独立せず、システムの複雑性が増加する。

Slide 28

Slide 28 text

|　© 2024 Levtech Co., Ltd. 28 ビックワードを避ける ドキュメントの品質を上げるためには？ Q. 新システムで現行システムのセッションストアからセッション情報を読み込むと？ A. 新システムのセッション管理が独立せず、システムの複雑性が増加する。 △ 漠然としていて、具体的な影響や問題点が分からない....

Slide 29

Slide 29 text

|　© 2024 Levtech Co., Ltd. 29 ビックワードを避ける ドキュメントの品質を上げるためには？ Q. 新システムで現行システムのセッションストアからセッション情報を読み込むと？ A. 新システムのセッション管理が独立せず、システムの複雑性が増加する。 △ A. 新システムのセッション管理が独立せず、新システムでの実装時に 現行システムのセッション管理を考慮する必要が生じる。 その結果、システム構成が複雑になることによる障害発生リスクの増加や、 開発工数の肥大化が予想される。 ⭕ 具体的な影響や問題点が分かりやすい！ ・自身が可能なところまで具体に落とす ・自身以外の数名に読んでもらった時に違和感がない

Slide 30

Slide 30 text

|　© 2024 Levtech Co., Ltd. 30 ● はじめに ● これまでの経験 ● ドキュメントって本当に必要？ ● ドキュメントの品質を上げるためには？ ● まとめ アジェンダ

Slide 31

Slide 31 text

|　© 2024 Levtech Co., Ltd. 31 まとめ ● 0→1での開発ではドキュメントが必要になることがあまりないため、 ドキュメントへの意識が薄くなりがち ● 運用を経験するとドキュメントの存在価値を身をもって知ることができる ● DORA の分析によれば、ドキュメントの品質と組織のパフォーマンスの間には 明確な関連性がある ● ドキュメントの品質を向上するためには、「検索性を上げる」「目的や達成できる ことを冒頭に記載する」「ビックワードを避ける」ことが重要

Slide 32

Slide 32 text

|　© 2024 Levtech Co., Ltd. 32 今日伝えたいこと 組織のパフォーマンスを上げるためには ドキュメントとその品質が欠かせない 再掲