Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
SRE活動を促進させるドキュメント技術 〜ドキュメントレビューって、どうやってる?〜
Search
kenta_hi
May 16, 2024
Technology
1
430
SRE活動を促進させるドキュメント技術 〜ドキュメントレビューって、どうやってる?〜
渋谷でビール片手にLT会!【SREどうでしょう】 第3木曜LT会 #5 で話しました。
kenta_hi
May 16, 2024
Tweet
Share
More Decks by kenta_hi
See All by kenta_hi
SREの組織類型に応じた リーダシップの考察
kenta_hi
2
900
SRE NEXT 2024 で形にした バトンを渡せる仕組み
kenta_hi
1
170
SREの組織類型におけるリーダーシップの考察
kenta_hi
3
3k
SRE Lounge #14 LT
kenta_hi
0
480
Other Decks in Technology
See All in Technology
LLMで構造化出力の成功率をグンと上げる方法
keisuketakiguchi
0
850
プロダクトエンジニアリングで開発の楽しさを拡張する話
barometrica
0
180
はじめての転職講座/The Guide of First Career Change
kwappa
5
4k
生成AI導入の効果を最大化する データ活用戦略
ham0215
0
160
Amazon Inspector コードセキュリティで手軽に実現するシフトレフト
maimyyym
0
120
Bet "Bet AI" - Accelerating Our AI Journey #BetAIDay
layerx
PRO
4
1.8k
AWS DDoS攻撃防御の最前線
ryutakondo
1
160
Delegate authentication and a lot more to Keycloak with OpenID Connect
ahus1
0
220
Instant Apps Eulogy
cyrilmottier
1
110
Rubyの国のPerlMonger
anatofuz
3
740
Foundation Model × VisionKit で実現するローカル OCR
sansantech
PRO
1
380
MCP認可の現在地と自律型エージェント対応に向けた課題 / MCP Authorization Today and Challenges to Support Autonomous Agents
yokawasa
5
2.4k
Featured
See All Featured
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
358
30k
Building a Scalable Design System with Sketch
lauravandoore
462
33k
Building an army of robots
kneath
306
45k
Designing Experiences People Love
moore
142
24k
No one is an island. Learnings from fostering a developers community.
thoeni
21
3.4k
Evolution of real-time – Irina Nazarova, EuRuKo, 2024
irinanazarova
8
880
Designing for humans not robots
tammielis
253
25k
Thoughts on Productivity
jonyablonski
69
4.8k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
PRO
183
54k
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
49
3k
Building Better People: How to give real-time feedback that sticks.
wjessup
367
19k
Unsuck your backbone
ammeep
671
58k
Transcript
SREの活動を促進させるドキュメントの技術 〜ドキュメントのレビューって、どうやってる?〜 @kenta.hi Topotal 2024/05/16
© Topotal, Inc. 自己紹介 名前 : 菱田健太 (@kenta.hi) 会社 :
Topotal 最近の活動 - SRE NEXT 2024 co-Chair - もう一度読むSRE - SRE as a Service 事例記事 - Waroom Meetup #1
© Topotal, Inc. Topotalについて SRE as a Service Embedded SRE
for customers
© Topotal, Inc. 今日話すこと 1. 話すこと a. このLTのゴールは、文章をレビューする時に気をつける点がわかること です b.
対象は、ドキュメントのレビューをする人です c. 文章の対象は、Issueやビジネスで利用する文章に限ります 2. 話さないこと a. 起承転結などの物語構成には対応しません b. 文法には言及しません
© Topotal, Inc. it isn't done until it is documented
1) 1) David N.Blank-Edelman.Becoming SRE. O’Reilly, 2024, 27P. テーマのきっかけ
© Topotal, Inc. Topotalについて SRE as a Service Embedded SRE
for customers 内製化を前提にSRE領域のコンサ ルテーションとエンジニアリングを提 供
© Topotal, Inc. 読みやすいドキュメントに仕上げるための レビューの観点を共有します
読みやすいドキュメントにするために
© Topotal, Inc. 読み手のほしい情報に過不足がない 自分が知ってる ドキュメントは、相手の知らない情報を自分の知ってる情報で埋め、行動を起こ す道具です。行動が起きない場合には、情報が不足しています。 相手が知ってる 相手が知らない 相手がわからない
行動を起こす 結果 情報を 伝える
© Topotal, Inc. 相手が知らない、相手がわからないを解消する 例えば、Why、What、Howのフレームワークで読んでも、わからないことがあります。これ は書き手が伝えるべき情報が認識できていないことに起因します。 各々で求められる情報の機能 情報の詳細 Why :
なぜやるか(目的)とその理由を伝える機能です なぜやるか(目的) その理由 やる背景 What : 目的に対して目的を満たす方法を1つ選び、その理由を伝える 機能、また選ばなかった方法とその理由を伝える機能です 目的を満たす方法をあげる その選択肢を選んだ理由 ほかを選ばなかった理由 How : 選んだ方法を具体的な行動を伝える機能です 具体的な行動をあげる
© Topotal, Inc. 読みやすいドキュメントって、どういうもの?? 1. 読み手のほしい情報に過不足がない 2. 文章の構成が読み手に負担がない 読みやすいドキュメントは、2つの「ない」が必要です。
© Topotal, Inc. 文章の構成が読み手に負担がない 読み手に負担がない構成は、文章を読み進めると情報が増えていく構成であることで す。例えば... 原文 端境となりやすい時期に天候不順が重なり、需給 が逼迫(ひっぱく)。 主要卸の1キロ価格は14日、ブロッコリー、キャベツ
ともに平年の2.5倍を記録した。 特にブロッコリーは過去 5年間で最高値と、異例の 水準となっている。2) 読み進めると情報が増える文 ブロッコリーの価格が 14日に平年の2.5倍になった。 理由は天候不良と端境の時期が重なり、需給が逼 迫したため。 特にブロッコリーの2.5倍は、過去5年間で最高値で 異例の水準となる。 2) YahooJapan Newsより引用 https://news.yahoo.co.jp/pickup/6501108
© Topotal, Inc. 文章の構成が読み手に負担がない 特にブロッコリーの2.5倍は、過去5年間で最高 値で異例の水準となる。 ブロッコリーの価格が14日に平年の2.5倍になった。 理由は天候不良と端境の時期が重 なり、需給が逼迫したため。 2.5倍の
追加情報 主張の理由 の追加 主張や目的に対して様々な情報(理由や補足、反対意見の打消)が増えていくと、読み 手に負担がありません。
© Topotal, Inc. ブロッコリーの価格が14日に平年の2.5倍になった。 理由は天候不良と端境の時期が重なり、需給が逼迫したため。 特にブロッコリーの2.5倍は、過去5年間で最高値で異例の水準となる。 文章の構成が読み手に負担がない レビュー側は、1つの文章がどのような機能を持っているかを確認しています。 2) YahooJapan
Newsより引用 https://news.yahoo.co.jp/pickup/6501108 主張 主張に対する理由 補足情報
© Topotal, Inc. おわりに 読みやすいドキュメントは、非同期で人を動かせる有益なツール です。みんなで読みやすいドキュメントを生み出していきましょう