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

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

Avatar for kenta_hi kenta_hi
May 16, 2024
Technology
520
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
6k
AI × Incident Response: What ’s Next?
Avatar for kenta_hi kenta_hi
0
400
SREの組織類型に応じた リーダシップの考察
Avatar for kenta_hi kenta_hi
2
1.1k
SRE NEXT 2024 で形にした バトンを渡せる仕組み
Avatar for kenta_hi kenta_hi
1
240
振り返り1_on_1のすすめ.pdf
Avatar for kenta_hi kenta_hi
0
340
SREの組織類型におけるリーダーシップの考察
Avatar for kenta_hi kenta_hi
3
3.3k
SRE Lounge #14 LT
Avatar for kenta_hi kenta_hi
0
530

Other Decks in Technology

See All in Technology
Oracle Cloud Infrastructure IaaS 新機能アップデート 2026/6 - 2026/8
Avatar for oracle4engineer oracle4engineer
PRO
0
130
10分で知る最近のOmarchy
Avatar for komagata komagata
0
130
OpenTelemetry eBPF Instrumentationの舞台裏 / Behind the Scenes of OpenTelemetry eBPF Instrumentation
Avatar for ymotongpoo ymotongpoo
3
320
2026-09-10 【Snowflake World Tour Tokyo 2026】dbt Core と Snowflake で実現する多層的なデータガバナンス / Multi-Layered Data Governance Powered by dbt Core and Snowflake
Avatar for civitaspo civitaspo
0
230
Webとヘルスデータ
Avatar for Yuku Kotani yukukotani
1
200
AI-DLCって実際どう？ 〜聞きたいこと全部聞いてみる〜
Avatar for 荒木 ARK news_it_enj
0
240
KPIだけでは評価できないプロダクトが考えるべき Evalsという第二の評価系 / Beyond KPIs: Evals as a Second Evaluation Framework for Products #PdEConf
Avatar for Aki / @LoveIdahoBurger aki_iinuma
4
3.8k
AI時代におけるプロダクト横断勉強会の設計
Avatar for ZOZO Developers zozotech
PRO
0
170
深夜のクラウド懺悔室 1:29:300 or 1:0:0
Avatar for kazzpapa3 kazzpapa3
0
190
Sigmaユーザーのための有用リソース一挙公開 & Sigmaで使えるMCP #sigma_ucj /useful-resources-for-sigma-computing-users-and-mcps-with-sigma
Avatar for shinyaa31 shinyaa31
0
160
synctest時代のhttptest Go 1.27で変わるHTTPサーバテストの裏側 / go conference2026 synctest and httptest
Avatar for Yoichiro Shimizu budougumi0617
1
210
ブラウザアプリの継続的パフォーマンスモニタリング (序) / Continuous Browser Application Performance Monitoring; Act 1
Avatar for moznion moznion
0
110

Featured

See All Featured
Bridging the Design Gap: How Collaborative Modelling removes blockers to flow between stakeholders and teams @FastFlow conf
Avatar for Kenny Baas-Schwegler baasie
0
690
SERP Conf. Vienna - Web Accessibility: Optimizing for Inclusivity and SEO
Avatar for Sara Fernández Carmona sarafernandez
2
1.6k
Redefining SEO in the New Era of Traffic Generation
Avatar for Szymon Słowik szymonslowik
1
410
Producing Creativity
Avatar for Steve Smith orderedlist
PRO
348
41k
Designing for Performance
Avatar for Lara Hogan lara
611
70k
First, design no harm
Avatar for Per Axbom axbom
PRO
2
1.3k
The Impact of AI in SEO - AI Overviews June 2024 Edition
Avatar for Aleyda Solis aleyda
6
1.2k
Optimizing for Happiness
Avatar for Tom Preston-Werner mojombo
378
71k
The Straight Up "How To Draw Better" Workshop
Avatar for Dennis Kardys denniskardys
239
140k
GraphQLの誤解/rethinking-graphql
Avatar for sonatard sonatard
75
12k
Primal Persuasion: How to Engage the Brain for Learning That Lasts
Avatar for Mike Taylor tmiket
0
440
Odyssey Design
Avatar for Ryan Kendrick rkendrick25
PRO
2
800

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. おわりに 読みやすいドキュメントは、非同期で人を動かせる有益なツール です。みんなで読みやすいドキュメントを生み出していきましょう