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
420
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
870
SRE NEXT 2024 で形にした バトンを渡せる仕組み
kenta_hi
1
160
SREの組織類型におけるリーダーシップの考察
kenta_hi
3
2.9k
SRE Lounge #14 LT
kenta_hi
0
470
Other Decks in Technology
See All in Technology
Sansanのデータプロダクトマネジメントのアプローチ
sansantech
PRO
0
200
衛星運用をソフトウェアエンジニアに依頼したときにできあがるもの
sankichi92
1
160
QuickSight SPICE の効果的な運用戦略~S3 + Athena 構成での実践ノウハウ~/quicksight-spice-s3-athena-best-practices
emiki
0
120
CDK Toolkit Libraryにおけるテストの考え方
smt7174
0
120
What’s new in Android development tools
yanzm
0
460
AWS認定を取る中で感じたこと
siromi
1
210
LLM時代の検索
shibuiwilliam
2
430
Lufthansa ®️ USA Contact Numbers: Complete 2025 Support Guide
lufthanahelpsupport
0
220
SREの次のキャリアの道しるべ 〜SREがマネジメントレイヤーに挑戦して、 気づいたこととTips〜
coconala_engineer
1
150
[SRE NEXT] ARR150億円_エンジニア140名_27チーム_17プロダクトから始めるSLO.pdf
satos
2
650
Lakebaseを使ったAIエージェントを実装してみる
kameitomohiro
0
160
PO初心者が考えた ”POらしさ”
nb_rady
0
220
Featured
See All Featured
BBQ
matthewcrist
89
9.7k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
507
140k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
248
1.3M
Documentation Writing (for coders)
carmenintech
72
4.9k
Making the Leap to Tech Lead
cromwellryan
134
9.4k
How to train your dragon (web standard)
notwaldorf
96
6.1k
GitHub's CSS Performance
jonrohan
1031
460k
The Cult of Friendly URLs
andyhume
79
6.5k
Into the Great Unknown - MozCon
thekraken
40
1.9k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
29
1.8k
Put a Button on it: Removing Barriers to Going Fast.
kastner
60
3.9k
Code Review Best Practice
trishagee
69
19k
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. おわりに 読みやすいドキュメントは、非同期で人を動かせる有益なツール です。みんなで読みやすいドキュメントを生み出していきましょう