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

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

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

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

kenta_hi

May 16, 2024
Tweet

More Decks by kenta_hi

Other Decks in Technology

Transcript

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

    Topotal 最近の活動 - SRE NEXT 2024 co-Chair - もう一度読むSRE - SRE as a Service 事例記事 - Waroom Meetup #1
  2. © Topotal, Inc. 今日話すこと 1. 話すこと a. このLTのゴールは、文章をレビューする時に気をつける点がわかること です b.

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

    1) 1) David N.Blank-Edelman.Becoming SRE. O’Reilly, 2024, 27P. テーマのきっかけ
  4. © Topotal, Inc. Topotalについて SRE as a Service Embedded SRE

    for customers 内製化を前提にSRE領域のコンサ ルテーションとエンジニアリングを提 供
  5. © Topotal, Inc. 相手が知らない、相手がわからないを解消する 例えば、Why、What、Howのフレームワークで読んでも、わからないことがあります。これ は書き手が伝えるべき情報が認識できていないことに起因します。 各々で求められる情報の機能 情報の詳細 Why :

    なぜやるか(目的)とその理由を伝える機能です なぜやるか(目的) その理由 やる背景 What : 目的に対して目的を満たす方法を1つ選び、その理由を伝える 機能、また選ばなかった方法とその理由を伝える機能です 目的を満たす方法をあげる その選択肢を選んだ理由 ほかを選ばなかった理由 How : 選んだ方法を具体的な行動を伝える機能です 具体的な行動をあげる
  6. © Topotal, Inc. 文章の構成が読み手に負担がない 読み手に負担がない構成は、文章を読み進めると情報が増えていく構成であることで す。例えば... 原文 端境となりやすい時期に天候不順が重なり、需給 が逼迫(ひっぱく)。 主要卸の1キロ価格は14日、ブロッコリー、キャベツ

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