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
880
SRE NEXT 2024 で形にした バトンを渡せる仕組み
kenta_hi
1
170
SREの組織類型におけるリーダーシップの考察
kenta_hi
3
2.9k
SRE Lounge #14 LT
kenta_hi
0
470
Other Decks in Technology
See All in Technology
Webの技術とガジェットで那須の子ども達にワクワクを! / IoTLT_20250720
you
PRO
0
120
室長の逆襲 :データ活用の陣地を増やすためのヒント
masatoshi0205
0
180
Expertise as a Service via MCP
yodakeisuke
1
140
QuickBooks®️ Customer®️ USA Contact Numbers: Complete 2025 Support Guide
qbsupportinfo
0
110
経理出身PdMがAIプロダクト開発を_ハンズオンで学んだ話.pdf
shunsukenarita
1
110
2025-07-25 NOT A HOTEL TECH TALK ━ スマートホーム開発の最前線 ━ SOFTWARE
wakinchan
0
120
低レイヤソフトウェア技術者が YouTuberとして食っていこうとした話
sat
PRO
7
5.8k
生成AIによる情報システムへのインパクト
taka_aki
1
130
株式会社島津製作所_研究開発(集団協業と知的生産)の現場を支える、OSS知識基盤システムの導入
akahane92
1
1.2k
Railsの限界を超えろ!「家族アルバム みてね」の画像・動画の大規模アップロードを支えるアーキテクチャの変遷
ojima_h
3
390
Bliki (ja), and the Cathedral, and the Bazaar
koic
8
1.3k
激動の時代、新卒エンジニアはAIツールにどう向き合うか。 [LayerX Bet AI Day Countdown LT Day1 ツールの選択]
tak848
0
540
Featured
See All Featured
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
33
2.4k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
34
5.9k
Scaling GitHub
holman
461
140k
Producing Creativity
orderedlist
PRO
346
40k
Evolution of real-time – Irina Nazarova, EuRuKo, 2024
irinanazarova
8
850
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
48
2.9k
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3.3k
Large-scale JavaScript Application Architecture
addyosmani
512
110k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
2.9k
Balancing Empowerment & Direction
lara
1
490
Building a Scalable Design System with Sketch
lauravandoore
462
33k
Dealing with People You Can't Stand - Big Design 2015
cassininazir
367
26k
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. おわりに 読みやすいドキュメントは、非同期で人を動かせる有益なツール です。みんなで読みやすいドキュメントを生み出していきましょう