10章 情報のため込み：ブレントだけが知っている
外から見ると、デプロイは簡単な活動のように見えます。しかしデプロイプロセスに深く入り込めば入り込むほど、素人の時にはわからなかった小さなステップに気付くことになります。
本人には当たり前、よく知らない人には簡単そう、いざやろうとした人には難しい。ここは、情報残さなくなるあるある。あるあるって認識して、とにかく残すをデフォルトにした方が幸せだと思ってます。(98lerr)
考えかたをデフォルトでのこす
なぜした？を書くのがハードル高いケース多い。何した、を書いてしまう。
10.1 どのように情報がため込まれているかを理解する
悪意に満ちた独裁者と見なすのは簡単です。このような組織の悪役が存在しないふりをしたいわけではありませんが、私の経験では、そういったケースは皆さんが思っているよりもずっと少ないのです。
「悪意を見出すな」ですね。そして「無能」でもないことがおおいと。(hayase)
ハンロンの剃刀、無能じゃなくて認識してないだけですが。
バックオフィスに座っているジェームズ・ボンドの映画に出てくるような悪役がすべてのWikiドキュメントを隠し持っているわけではないとしたら、このような情報のサイロ化を促進しているのは何なのでしょうか。それは、組織構造・インセンティブ・優先順位・価値観の組み合わせであり、それらすべてによって誰もドキュメントをリポジトリサーバで共有しないという状況を作り出しています。
チームとして情報を残そうと決めて、どれだけ周囲に貢献しましたか？を話す機会をつくったら意識的に書いてもらえること多かったです。なんらかの形のインセンティブは大事ですね。(98lerr)
手応えを感じて，前にすすんでいけるのが、エンジニアとして大切だなと思いました(hayase)
10.2 意図せずに情報をため込んでいる人を認識する
ヨナの例はわかりやすくていいなっておもう。これからどこかでプレゼンする時にはここを引用したいな。何かを伝える時に毎回こういうエピソードを創作しないようにしたい。
概念実証後に捨てるにはすでにあまりにも価値があるものになっていました。
(ここ本題ではないんですが) それでも一度捨てて作り直すべきなのかなと思っています。ドキュメントも含めて、PoCは負債をためこんでいるはずなので。 (hayase)
「テストをなぜかかないか」のこたえの1つが「PoCのコードがテスト可能でないから」(98lerr)
PoCがおわったら、今までのコードは捨てる。ドキュメント(ADRなど)は残す。
PoC終わった時が一番賢い！
システムリプレースに必要なものをドキュメントに残す！
このプロジェクトは流動的であり、いつになるのかもわからない「安定」状態に達するまで、ドキュメント作成は先送りされ続けています。
後でやろうは一生来ない。システム運用全般でいえる原則。(98lerr)
組織の中で最も危険なものの1つは、古いままの詳細なドキュメントです！ 古い情報に基づいて行われた決定は、プロジェクトに波及する可能性があります。ドキュメントに具体的な実装の詳細を書くよりも、動機や背景、戦略について書くことの方がはるかに優れています。
古いドキュメントを、古いと共有することだけでも価値がある(みんなそれを見なくて済む)という話を最近した。(98lerr)
古い、価値の薄い詳細が残ってることで、何か大事なことを直そうと思っても「全部直すのか」と思って腰が重くなる。
動機や背景は、詳細な仕様が追従してなくても、長期間大事な情報として残り続けるのでほんと書いて欲しい。(98lerr)
「同期と背景」に +1 (hayase)
ドキュメントは最終的なゴールではありません。最終的なゴールは情報の共有です。……ドキュメントの価値は、それを作成するための機会費用を上回るものでなければなりません。
アジャイルでない背景の人では、ドキュメンテーションが目的になっている場合も多かったりするので、この観点はいつも忘れないようにしたい。(hayase)
最後にあると「足りないから」「納品物に必要だから」でここに陥りやすいですね
私がこれまでのキャリアの中で発見した興味深いことは、ドキュメントを取り巻く中でその人がどの位置にいるかによって、人々のドキュメントに対する価値観が異なる傾向にあるということです。
ここが難しいところと思ってます。ドキュメント残す立場の人やその周囲は割と常識だから残す必要ないと考えて、いざその人がいなくなった時に残った人が価値を感じる。なので、考え方は基本残して欲しい。(98lerr)
上の議論の通り、何を残すのかが大事なのかなと思いました。「とにかく書こう」だと「古いままのドキュメント」を量産することになってしまいますので。(hayase)
ドキュメントは、自動テストできないのがつらい。
10.2.2 抽象化 vs. 難読化
「vs 難読化」なのですか! (hayase)
抽象化の定義を書いているのが印象的だったkyon_mm.icon
抽象化は色々出てくるので、ここでどういう目的で使ってますを言ってくれていて読みやすい。
この抽象化のもう一つの問題点は、チーム間に突然壁を作ってしまうことであり、これがしばしば悪い行動を助長してしまいます。
自分はよくわからない、で知らなくて良い扱いになるのはあるある。そこで組織の壁もあると敵対関係にまでなることも。交流する場(一緒に活動する意識を残す場)は作っていかないとですね。(98lerr)
大多数の人は「鍵のかかった扉」を前にして、この扉の向こうにあるものは自分には関係ないと思い込んでしまいます。
ドキュメント書く余裕ないから、とりあえず行間読んでくれる人だけ見てくれる限定アクセスのスペースにおこう→アクセスできない人から質問→時間がなくなる→... となると悲しいので、ハードル低くおける場所を作るの大事ですね(98lerr)
オープンにすると、責任が見えなくなり、ドキュメント書かない（じぶんじゃなくていい）になることも
「米国人は書かれていないことはすぐに手を抜くため、当たり前のことを漏らさず書くのが重要なのだ。」「FedRAMPが中小企業に対する参入障壁になっているという批判」
DevOps は 効率化？ セキュリティ？の考えの違い。
抽象化はいいぞ！って文脈じゃなくて、抽象化することによるデメリットも触れられていて実務的だなーって思いました。kyon_mm.icon
10.2.3 アクセス制限
何かを安全性の高いフォルダに置くと決める前に、それが本当にWikiのそのようなアクセスが制限された場所に置く必要があるかどうかを評価する必要がある
Webサービスのドキュメントが、部署以外からまったく見えないようにしてしまっている..（どこかのタイミングで決めちゃった） ある意味情報の溜め込みをしてるなあ.. （他サービスのはだいたい見えるから、なんか申し訳ない
まよったら安全に倒す、で考えた結果、みんな周りから見えないところに置くってありますね。(98lerr)
見せていいものと見せていけないものが一つのドキュメントに混ざっていると、見せないところに寄りがち
10.2.4 ゲートキーパーの行動を評価する
将来的には、それぞれの情報を依頼する人自身で対処できるようにする方法を検討する必要がある」
その通りだと思う。そんなに難しくはない気がする。自分はちょっとセキュリティ関わる領域のゲートキーパーをしているので難しいところもある.. なやましい
監査もセキュリティも、閉める話だけで大変なんですが、制約の中でどううまくやれるかを相談できる状況になるよう、双方に動けるかたちができるといいですね
早い断段階からの参画でうまくいくかも
10.3 コミュニケーションを効果的に構築する
トピックを定義する。
対象者を定義する。
キーポイントを説明する。
最後に行動を喚起する。
4つのステップで整理しているんだけど、思いの外普通のこと。でも、あらためて大事なんだよなーっておもった。 kyon_mm.icon
+1 (hayase)
+1 (98lerr)
+1(mikiso)
ドキュメントの作成や知識の伝達は、誰もが日常業務の中で行うことが期待されるタスクですが、実際には明確な指示と優先順位付けがなければ、チームがエンジニアに課すほかの要求に負けてしまいます。
改善もドキュメントも、この悩み。組織の状態によっても原因様々なので、いくつも例を書いてくれていて嬉しい。(98lerr)
コアポイントとカラーポイントでわけるのやれていないなーっておもった。スライドやドキュメントだと整理できているけど、ちょっとした会話ではあまりできていない気がする。コアポイントだけでコミュニケーションしがちかなぁ。。。kyon_mm.icon
10.4 知識を発見可能にする
10.4.1 ナレッジストアの構築
共通の辞書を使用する。
1つのマスタドキュメントにリンクされた、階層構造のドキュメントを作成する。
部門ではなく、トピックを中心に文書を構成する。
この３つのポイント定期的にチャットに貼りたいなw kyon_mm.icon
忘れたころに思い出せるようにしておくのいいですね。(98lerr)
大事だけれど、大事だとわかってる人が頑張り、周りの人はそうでもないがおきがち
メンテされない、見られてもいない
更新したこと、ドキュメントをつかったこと、共有すると更新されるのが循環される
読みやすいところに置いておくの大事！
ポータルのトップ、みんなが大事と思うことの主張合戦になって埋もれることも ;-(
チームが新しいプロダクトを開発しているとき、そのプロダクトはしばしば、それを作ったプロジェクトの名前を引き継ぐことがあります。
あるある。そのままじゃなくても、新とか次期とかつけたやつ。せめて、名前を決める時期は決めたいですね。そのうちではなく。(98lerr)
Wikipediaを例にしながら、実際のプロダクトへの適用例となるようなドキュメント構造について例示があるので、取り組みやすいなーって思ったし、他の人に説明する時にWikipediaの例は非常に納得してもらいやすそうkyon_mm.icon
+1 (98lerr)
wikipedia, いい具体例。
「いいドキュメントサンプルがない」という前にwikipediaの構造をみてみたい。
wikipedia の構造はデファクトスタンダードでもありそう
ドキュメントが古くなってしまう理由の一つは、つじつまが合わない点を見つけて、それを修正するための行動を起こす目が少ないことです。
↓の参照されることが大事という以外に、実態との乖離を防ぐ方法はないのかな。実装よりのドキュメントなら、文芸的プログラミング(ドキュメンテーションコメント)の方向で解決できそうだけど。(hayase)
運用の話で行くと、こんなところで変更管理回したくないっていうので手が止まるとか、ため込む場合も。軽微な修正とか、例や分けすればいいんですが。(98lerr)
誤字修正やUI微調整でドキュメント更新したくないし、しなければならないのだったらドキュメントがおかしいのかも(hayase)
どこ直すか分からないケースとか
複数個所に修正があると、全部洗いだす時間がなくてあきらめるとか
つじつまが合わなくなるとか
ドキュメント内だけじゃなく、複数ドキュメントの階層。いきなり任されてそこを整理出来てないことも。
一番最初に整理してルール決めても、書いてみると合わないことも。そういう時、ファイル管理とかだと「もう整頓するの無理」ってあきらめがち
ドキュメント体系のリファクタリング！
ドキュメント自体の優先度低いのに、ドキュメントのリファクタに挑むなんて。。。
ドキュメントリファクタリング支援ツールほしい！
マスタドキュメントのアプローチのもう一つの利点は、より多くの人の目に触れることです。(中略) 10人で1つのWikiドキュメントに取り組んでいる場合、そのドキュメントの作業の80％は2人が行っている
ここにパレートの法則を持ってくるのがおもしろい。ドキュメントを色んな人の目に触れる場所に置くから改善や追記も進む、というのがわかりやすい。(98lerr)
+1(mikiso)
意外と自分が頑張ったのが、他人に伝わってないことも多い。
Confluence, PV も見れる。
10.4.1.3 部門ではなくトピックを中心に構成する
思い切りこのアンチパターンを踏んでた.. 今日なおそう.. (mikiso)
10.4.2 学習の習慣付け
学習や知識の共有に関しては、価値があるだけでなく、文化の一部として自立するような習慣を作りましょう
文化の一部として自立するとは？どんな条件が必要？(mikiso)
社内のナレッジ共有が習慣付いてるとか？
普段だと週１くらいで、仕事に関係のない技術の話をふるようにしています kyon_mm.icon
今の仕事に直結しない話が普段されてるのが、文化の一部になった一つかも。
SME(Subject Matter Experts)は自分の専門分野に関連した依頼を受けることで頭がいっぱいになり、通常の日常業務以外の時間を要求される
まさにブレンドの例。教わった人が、理解確認のためにもドキュメント化するっていうのが一つ望ましい形だと思っています。(98lerr)
たしかに。教わった人がドキュメント化するの、いいですね。あまり今まで見たことありませんでしたが(mikiso)
+1 (hayase)
私もSMEやってますが「知識伝達が大事な業務だからちゃんとやってね」ということを最初に開発部長に言われた
仕事のスコープをすごく限定してもらっているけど、SMEへの要求の悪循環を回避するためなのかもしれない(mikiso)
自分の仕事がSMEがおおいので、めっちゃわかりみの塊でした。。。kyon_mm.icon
これの姉妹本がThe DevOps ハンドブックです。
Phoenix Project : 小説であるある話をまとめた本
The DevOps ハンドブック : メソドロジーとしてまとめた本
ランチ＆ラーンのスケジュールを立てる際には、質問の時間を十分に確保することが重要です。イベントを成功させるには参加者との対話が重要です。
ここ、「質問されると思うと身構えて来ない人がいるかも」とか「いっぱい聞きたいから発表を詰め込む」とかで質問パートを削ろうとする話も出なくもないのだけれど、やっぱり質問してもらうから相互やりとりもあるし、発表者も発表しがいもあるし、聴講者もtakeだけじゃなく入っていけるので、欠かせない。(98lerr)
実施したい気持ちはあるけど、メンバーの働き方・休み方が揃ってないので、環境が作れずにいます。(hayase)
これはとても簡単です。この部分は簡単です。そのため……となるのは明らかです
この例にあるようなよくない話し方をしてしまうの、けっこうあるなーっていう自戒がうまれました。 kyon_mm.icon
98lerr イベントでベテランがいるっていうことをいうとまわりの初心者にプレッシャーをかけてしまう
わかる！！！自戒 kyon_mm.icon
プレゼンの最後に、行動を喚起するためにお願いすること
あなたが助けを求めていることは何ですか？ / どのように行動を起こせばいいでしょうか？ / 期限はいつまででしょうか？
いま仕事で情報をいい感じに流通させるためのプレゼンを作っている。
とくに行動してほしいことはないのだけど、うまいやり方があるだろうか.. (mikiso)
プレゼントはなに？って考えるといいかも 98Ierr
エモ倒している！！！いい話だ kyon_mm.icon
「ご清聴ありがとうございました」のスライド写し続けるのはもったいない 98Ierr
わかりみ
撲滅委員会
+1 98lerr
10.4.2.2 ライトニングトーク
ライトニングトークは、このようなトピックを掘り下げ、参加者に仕事のヒントやコツを共有するのに最適な形式です。
一言いいたい便利なモノ、ってみんなあるけれど、機会無くて言わないというの結構ある。LTとか、OSTとか、気になるトピックをテンポよく、あるいは軽量に話す場が職場にある(一緒に仕事する仲間と出来る)のは大きな価値になると思う。(98lerr)
tips を話す会とかもやりました (98lerr)
また、大まかな概要の紹介もライトニングトークのテーマとして最適です。エンジニアは、自分がよく把握していないプロセスや組織で仕事をすることがあります。
これも大事。自分たちのやってること、隣がよく知らないけれど知ってると活用シーン多いもの結構ある。かしこまった報告会での共有という形も効果あるんですが、もっと「魅力を伝えたい」くらいの熱量で話せる場でないと伝わらないものも多い。あわせて、そういう話をしてることが自分たちの魅力を再認識させるのにもいい。(98lerr)
自分の隣の人が何をしているか、どうやって提供してくれる情報を作っているか、ぜひ知りたい(hayase)
トークの最後にはそのトピックに関する詳細情報をまとめたスライドを用意しましょう
学習の旅を続けるための追加リソースを示す mikiso
10.4.2.3 外部イベントのホスト
イベントをホスティングしてくれる企業の気持ちがはじめてわかりました。これまで提供いただく側のことが多かったので。 (hayase)
仕事終わってからとか
オフィス見て会社の雰囲気見るのいいですよね
これらのグループに自分たちのオフィスを提供することは、学ぶためのすばらしい方法です。あなたのチームメンバーの中には、おそらく仕事以外にもやらなければならない用事が多く、社外の技術コミュニティに参加することが難しい人もいるでしょう。しかし、そのようなコミュニティを自分の職場に持ち込めば、参加したり社外の人とネットワークを作ったり学ぶことが容易になります。
まずは職場での飲食付きイベントから、っていうのが自身の現在地です。(98lerr)
10.4.2.4 ブログ
正式なドキュメントの場合、心の中でビジネスパーソンとしての自覚が芽生え、無駄に堅苦しい文章になってしまいます。(中略)しかしブログの場合は、形式的ではなく、構造的でもなく、創造的な自由度の高い文章を書くことができます。
気軽にアウトプットできるようにしていくのは広めたい。かしこまってしまいがち。(98lerr)
社内のチーム外に向けてだけでも、効果はありそう。社内でもエンジニア外が見えるとか。
またブログ記事は時系列順に並んでいるので、各記事はあくまでその時点での内容になっているということが明確となる点も便利です。ドキュメントが Wiki やそのほかの公式ドキュメントリポジトリに置かれていると、それらは暗黙的に常に更新されており、最新のものであると考えられがちです。
この観点も気付いていませんでした。更新の義務(感)がなくなるのは良いですね (hayase)
blog を LLM で要約してドキュメントを生成したい (hayase)
ドキュメント → メンテし続けるのが大変、ブログ → スナップショット（日付付き）
10.5 チャットツールの有効活用
このような場合には小さくて短命なチャンネルを使うことをお勧めします。これは特に、議論する問題点がチケット管理システムのチケットに記録されている場合に有効です。
スレッドが作れるチャットでも、これは同様なのだろうか？ この本執筆時点のSlackはスレッドを作れなかったような記憶があり、その前提で書いてます。 (98lerr)
スレッドよりも、チャネルの方が終わりが明確になりそう
チャンネルを分けることのもう一つの利点は、そのトピックに関する会話の終わりが明確になる
上の疑問に対する一つの回答かも。スレッドでもスレッド終了時点はできますが、より明確になるかもしれない。(98lerr)
10.5.1.3 定期的に自分のステータスを更新する
チャットアプリケーションでは自分の現在のステータスを更新できます。できるだけ頻繁に利用して、現在の状況を正確に反映しましょう。私の場合、割り込まれたくないときは「取り込み中」というステータスを使います。これは、深い思考を要する仕事で途切れのないまとまった時間が必要なときに使います。このステータスを設定し、通知をオフにして、その間に集中して仕事をします。
Outlook でやたらと会議が入ってきて、参加しない定例とかをキャンセルしないでいると体が空いてるのに忙しいみたいなステータスになってたり、あわただしくなったときほど扱いが雑になっていることが。改めてステータスが人にどう見えてるか、意識しようと思いました。(98lerr)
10.5.1.4 チャンネル全体への通知の利用を制限する
誰に質問をすれば良いのかわからないとき、ユーザーはチャンネルに入って、@here、@allや@channelといった形でチャンネル全体に通知やブロードキャストを行うことがあります。これは、できるだけ避けましょう！
これを乱発してるチャンネルは、オオカミ少年的に捉えて確認する優先度を下げようと思ってしまってる自分を認識してます。(98lerr)
一方で、個人メンションばかりしてると属人的な状態がキープされるっていう話もあったりしました。チームで受けるような話はチームの小さなタグを作るとかするのがよい(all とかにしない) と思うのですが、どうでしょう？ (98lerr)
10.5.2.1 チャットボットの利点
もう一つの利点は、これらのコマンドとその出力が、ほかのすべてのチャンネル参加者も見える形でチャンネル内で行われることです。
対応してる状況が関係者全員に視覚化されるのは、たしかにいい。インシデント対応だと「これ誰かやった？」「いまやったんでチャットに貼ります」みたいなやり取りは多く起きる。(98lerr)
書いてもらう文化が定着しないと辛い
インシデント対応とか、声で話してるのを記録しないままになるとか
メモ作るとき、割り込んでいいかの悩みもある
10.6 本章のまとめ
SMGのタイプに応じて、さまざまな形式で知識共有することを許容しましょう。
SMG ってなんでしたっけ？(98ler)
Allow knowledge sharing to occur in different formats for different types of subject- matter experts.
専門知識の種類ということぽい。
web版はSMGだが、pdf 版だと SMEなので、誤植っぽい。
みんなからのコメント
実践する/伝えるためのハードルはなにか？
情報伝達をするための時間をさくためには現場での工夫よりも、リーダーシップやアサインマネジメントのほうが影響が大きいが、それらに対する自分達の権限がないとか
一緒に使うと良さそうなプラクティスやマインドセットはなにか？
上長にランチ&ラーンとかに一緒にでてもらうとか？
上長にブログのトピック出しを一緒にやってもらって、レビューもしてもらうとか？
ハードルの乗り越え方はなにか？実践/伝える方法はなにか？
どれくらい効果がありそうか？