Upgrade to Pro — share decks privately, control downloads, hide ads and more …

SRE活動を促進させるドキュメント技術 〜ドキュメントレビューって、どうやってる?〜

Avatar for kenta_hi kenta_hi
May 16, 2024
Technology
510
1

SRE活動を促進させるドキュメント技術 〜ドキュメントレビューって、どうやってる?〜

渋谷でビール片手にLT会！【SREどうでしょう】 第3木曜LT会 #5 で話しました。

Avatar for kenta_hi

kenta_hi

May 16, 2024

More Decks by kenta_hi

See All by kenta_hi
事業価値を⽣み出すSREへ SREが担うべき意思決定の5層
Avatar for kenta_hi kenta_hi
2
5.5k
AI × Incident Response: What ’s Next?
Avatar for kenta_hi kenta_hi
0
390
SREの組織類型に応じた リーダシップの考察
Avatar for kenta_hi kenta_hi
2
1.1k
SRE NEXT 2024 で形にした バトンを渡せる仕組み
Avatar for kenta_hi kenta_hi
1
230
振り返り1_on_1のすすめ.pdf
Avatar for kenta_hi kenta_hi
0
330
SREの組織類型におけるリーダーシップの考察
Avatar for kenta_hi kenta_hi
3
3.3k
SRE Lounge #14 LT
Avatar for kenta_hi kenta_hi
0
520

Other Decks in Technology

See All in Technology
Kiro入門｜仕様駆動開発で変わるAI時代の開発スタイル
Avatar for 工藤皓夢 cmkudo
0
230
Kiro Crew入門 - 常駐エージェントの仕組みと使いどころ / Intro to Kiro Crew
Avatar for Kazuki Adachi k_adachi_01
1
600
会社紹介資料 / Sansan Company Profile
Avatar for Sansan, Inc. sansan33
PRO
24
430k
コーチングの奥義 何もしないテクニック
Avatar for Watanabe Jin jinwatanabe
0
140
SmartHR Engineering Team Deck
Avatar for SmartHR, Inc. smarthr
1
3k
形式手法特論：Hyperproperty とモデル検査 #kernelvm / Kernel VM Study Tokyo 19th
Avatar for y_taka_23 ytaka23
0
150
20260807_第6回_関東kaggler会LT_claw系bot xangiと始める、"寂しくない" kaggle
Avatar for suguuuuuすぐー sugupoko
0
370
AI・HPC開発を支えるGPU環境の新しい選択肢 液冷GPUシステム「AquSys」の取り組み
Avatar for GPU UNITE gpuunite_official
0
130
Model Studio CLI × Token Plan
Avatar for 尾関将樹 | めい maigo999
0
200
DatadogのBits Chatが開発組織にもたらしたもの / What Bits Chat Has Brought Us
Avatar for SMS tech sms_tech
1
290
MulticaとPi Coding Agentで、小規模OSSを30本同時運用した流れ
Avatar for eiei114 eiei114
0
130
【GCC2026】鉄拳8でのVFX開発事例
Avatar for Bandai Namco Studios Inc. bandainamcostudios
PRO
0
120

Featured

See All Featured
Six Lessons from altMBA
Avatar for Skipper Chong Warson skipperchong
29
4.4k
Rebuilding a faster, lazier Slack
Avatar for samanthasiow samanthasiow
85
9.6k
Measuring Dark Social's Impact On Conversion and Attribution
Avatar for Stephen Akadiri stephenakadiri
2
260
State of Search Keynote: SEO is Dead Long Live SEO
Avatar for Ryan Jones ryanjones
0
250
A brief & incomplete history of 
UX Design for the World Wide Web: 1989–2019
Avatar for Jason CranfordTeague jct
2
480
Building a Scalable Design System with Sketch
Avatar for Laura Van Doore lauravandoore
463
34k
Skip the Path - Find Your Career Trail
Avatar for Mark Kilby mkilby
1
190
The Curious Case for Waylosing
Avatar for Cassini Nazir cassininazir
1
470
Facilitating Awesome Meetings
Avatar for Lara Hogan lara
57
7.1k
Design of three-dimensional binary manipulators for pick-and-place task avoiding obstacles (IECON2024)
Avatar for konakalab konakalab
0
550
How to Get Subject Matter Experts Bought In and Actively Contributing to SEO & PR Initiatives.
Avatar for Liv Day livdayseo
0
170
We Analyzed 250 Million AI Search Results: Here's What I Found
Avatar for Josh Blyskal joshbly
1
1.8k

Transcript

  1. SREの活動を促進させるドキュメントの技術 〜ドキュメントのレビューって、どうやってる？〜 @kenta.hi Topotal 2024/05/16

  2. © Topotal, Inc. 自己紹介 名前 : 菱田健太 (@kenta.hi) 会社 :

    Topotal 最近の活動 - SRE NEXT 2024 co-Chair - もう一度読むSRE - SRE as a Service 事例記事 - Waroom Meetup #1

  3. © Topotal, Inc. Topotalについて SRE as a Service Embedded SRE

    for customers

  4. © Topotal, Inc. 今日話すこと 1. 話すこと a. このLTのゴールは、文章をレビューする時に気をつける点がわかること です b.

    対象は、ドキュメントのレビューをする人です c. 文章の対象は、Issueやビジネスで利用する文章に限ります 2. 話さないこと a. 起承転結などの物語構成には対応しません b. 文法には言及しません

  5. © Topotal, Inc. it isn't done until it is documented

    1) 1) David N.Blank-Edelman.Becoming SRE. O’Reilly, 2024, 27P. テーマのきっかけ

  6. © Topotal, Inc. Topotalについて SRE as a Service Embedded SRE

    for customers 内製化を前提にSRE領域のコンサ ルテーションとエンジニアリングを提 供

  7. © Topotal, Inc. 読みやすいドキュメントに仕上げるための レビューの観点を共有します

  8. 読みやすいドキュメントにするために

  9. © Topotal, Inc. 読み手のほしい情報に過不足がない 自分が知ってる ドキュメントは、相手の知らない情報を自分の知ってる情報で埋め、行動を起こ す道具です。行動が起きない場合には、情報が不足しています。 相手が知ってる 相手が知らない 相手がわからない

    行動を起こす 結果 情報を 伝える

  10. © Topotal, Inc. 相手が知らない、相手がわからないを解消する 例えば、Why、What、Howのフレームワークで読んでも、わからないことがあります。これ は書き手が伝えるべき情報が認識できていないことに起因します。 各々で求められる情報の機能 情報の詳細 Why :

    なぜやるか（目的）とその理由を伝える機能です なぜやるか（目的） その理由 やる背景 What : 目的に対して目的を満たす方法を1つ選び、その理由を伝える 機能、また選ばなかった方法とその理由を伝える機能です 目的を満たす方法をあげる その選択肢を選んだ理由 ほかを選ばなかった理由 How : 選んだ方法を具体的な行動を伝える機能です 具体的な行動をあげる

  11. © Topotal, Inc. 読みやすいドキュメントって、どういうもの？？ 1. 読み手のほしい情報に過不足がない 2. 文章の構成が読み手に負担がない 読みやすいドキュメントは、2つの「ない」が必要です。

  12. © Topotal, Inc. 文章の構成が読み手に負担がない 読み手に負担がない構成は、文章を読み進めると情報が増えていく構成であることで す。例えば... 原文 端境となりやすい時期に天候不順が重なり、需給 が逼迫（ひっぱく）。 主要卸の1キロ価格は14日、ブロッコリー、キャベツ

    ともに平年の2.5倍を記録した。 特にブロッコリーは過去 5年間で最高値と、異例の 水準となっている。2) 読み進めると情報が増える文 ブロッコリーの価格が 14日に平年の2.5倍になった。 理由は天候不良と端境の時期が重なり、需給が逼 迫したため。 特にブロッコリーの2.5倍は、過去5年間で最高値で 異例の水準となる。 2) YahooJapan Newsより引用 https://news.yahoo.co.jp/pickup/6501108

  13. © Topotal, Inc. 文章の構成が読み手に負担がない 特にブロッコリーの2.5倍は、過去5年間で最高 値で異例の水準となる。 ブロッコリーの価格が14日に平年の2.5倍になった。 理由は天候不良と端境の時期が重 なり、需給が逼迫したため。 2.5倍の

    追加情報 主張の理由 の追加 主張や目的に対して様々な情報（理由や補足、反対意見の打消）が増えていくと、読み 手に負担がありません。

  14. © Topotal, Inc. ブロッコリーの価格が14日に平年の2.5倍になった。 理由は天候不良と端境の時期が重なり、需給が逼迫したため。 特にブロッコリーの2.5倍は、過去5年間で最高値で異例の水準となる。 文章の構成が読み手に負担がない レビュー側は、1つの文章がどのような機能を持っているかを確認しています。 2) YahooJapan

    Newsより引用 https://news.yahoo.co.jp/pickup/6501108 主張 主張に対する理由 補足情報

  15. © Topotal, Inc. おわりに 読みやすいドキュメントは、非同期で人を動かせる有益なツール です。みんなで読みやすいドキュメントを生み出していきましょう