アート・オブ・アジャイルデベロップメント読書会 7.7 ドキュメント
===
###### tags: `アートオブアジャイルデベロップメント読書会`

[読書会インデックスページ](https://hackmd.io/qzr55OUxR_aKBNKZjRaxwA?view)

# Discord開始位置

* [connpass募集ページ](https://agiledevs.connpass.com/event/193498/)
* ハッシュタグ: [#agile_devs](https://twitter.com/hashtag/agile_devs)
* [discord:2021/xx/xx]()

# 自己紹介

- ファシリ役
-
- 読み上げ役
-

# 参加の仕方

- マイクはいつでもONにして、話に参加して結構です。
- テキストチャットでも、コメントやリアクションでどんどん参加してください！ラジオ担当が拾っていきます。
- 聞いているだけの方もOKです！

# ディスカッションをより豊かにするためのグランドルール

[アートオブアジャイル輪読会はじめの1歩 - Speaker Deck](https://speakerdeck.com/t2kob/atoobuaziyairulun-du-hui-hazimefalse1bu)

- 参加者は毎回任意
- 今回は不参加、次回は参加をするといった気軽な感じ
- 途中参加も断然OK! まずは聞くだけでも大丈夫です！
- フィードバックを恐れない
- マサカリは怖いと思いますが、アウトプットからのフィードバックを受け、学びを深めていきましょう
- アウトプット7割：インプット3割の気持ちで臨みましょう！
- 経験の有る無しは気にしない
- 自分はアジャイル非経験者だから……と気後れする必要はないです
- 堂々と意見や疑問を語りましょう
- ページ数と同時に、節のタイトルやキーワードを言って頂けるとスムーズです
- 電子書籍で読んでいるとページ数ではわからないため
- 話していない人が、率先してメモしましょう
- このHackMDはみんなのものです。どんどん書いていきましょう:+1: :+1: :+1: :tada:
- 気になる質問や同感するものには :+1: を末尾につけてください。

# タイムテーブル

| 時間 | 所要時間 | 内容 |備考 |
| -------- | -------- | -------- | -------- |
| 19:30- | - | もくもくタイム（hackmd書き込み） | |
| 20:00-20:15 | 15分 | 当日の流れとグランドルールの共有 | |
| 20:15-20:25 | 10分 | 参加者アンケート | |
| 20:25-20:35 | 10分 | 感想記入&HackMDに書かれた皆さんの感想・気づき・疑問をもっと掘り下げたいものを、 :+1: 付けていく | |
| 20:35-21:45 | 70分 | 本の節ごとにディスカッション（ここでも適宜、HackMDに気づきとか書いていってもらっていいです） | |
|21:45-21:50 | 5分 | [miro](https://miro.com/welcomeonboard/OW54WlJIZ3pKQlBwbUtTc0p3d1Y3UlJOWWgycGx4S2ZLZGpyUGtVeXRCOG1HUUs3QnJVREwzY29LOTJnSU1UeXwzMDc0NDU3MzQ3MDA4ODU5ODI5)を使ってふりかえり | |
| 21:50-21:55 | 5分 | 次回開催日と読む範囲決めてクローズ | |

* 流れ
* 10分ごとにトピックを区切って議論します
* 10分経った段階できりがよければ次の話題に、そうでなければ延長します
* 議論するトピックは最初に「いいね」がついた数の多い順です。
* 「疑問・参加者に聞いてみたいこと」→「感想・気づき」の順番で進めます
* その前に、議論するトピックを決めるための投票を行います
* ひとり1トピックには1票、全体では何票でもOKです

# 下に感想などを書いていって下さい。どんな些細なことでもOKです。

### 目安の時間

- 1トピックにつき10分を予定しています
- 盛り上がったら延長することもあります

## 疑問・参加者に聞いてみたいこと

- 元々ドキュメントを作成する文化・習慣が乏しかった環境で、ドキュメント作成を浸透させるにはどうしますか？:+1:
- みなさん普段ドキュメントに残しているもの、残した方がよかったと思うものはなにがありますか？:+1::+1::+1:
- おすすめのドキュメント管理ツールは？ :+1::+1:
- 松岡おすすめはnotion！

- 記事の共同所有のようなことをもっと実現したいのですが、なかなか失敗やひっかかってしまった所を追記してくれる人が居ません。皆さんこのあたり上手くいっていますか？

## 感想・気づき

- 7.7　ドキュメント
- まず、ドキュメントの種類を3つにきちんと整理されているのが目から鱗
- > ドキュメントは全てコミュニケーションの一つの形だ:+1::+1:
- こんな捉え方もしたことなかった！　　　　　　　　　　
- ドキュメントをどのように位置付けて取り扱うか、という観点だけで、どのように作るのか、どのように「死なない」ように維持するか、どのように共有するか、などドキュメントの価値を高め、メンテするか、という視点がないのがとても残念。ドキュメントの意義を軽視している、と捉えられてもしかたない、という気持ちを持った。

- 著者サイトのコラム https://www.jamesshore.com/v2/blog/2008/the-documentation-myth
- ドキュメントは何のため？書かないのはなんで？というのもお面白い話。:+1::+1::+1::+1:
- このhackmdの最後のところに、和訳文足しました。

- 7.7.1　中間ドキュメント
- > 対面のコミュニケーションに代わるものはない。電話でさえ、会話の重要なニュアンスが失われてしまう。

本書全体を通じて、対面であることをかなり重要視している印象。対面の価値には同意するが、そこまでなんだろうかとは思う。
- 電話でも、というのは意外。そこはあんまり体感とは合わないけどそうだろうか・・・？

- 7.7.3　引継ぎドキュメント
- > 目標はソフトウェアを作るあいだに学んだ最も重要な情報をまとめることだ。
- 「学んだ」というのは新しい、その観点で捉えたことはなかった

- 7.7.4　質問
- > 本当のリスクは、プロジェクトに相応なコミュニケーションの量や質が低下することだ。

目的を忘れずにいたいですね。ドキュメントをつくるべき！口頭でやるべき！とどちらか一方により過ぎるのはよくない。 :+1::+1:

- > 1 つのコミュニケーション手段に固執してはいけない。書面でのコミュニケーションを好むと、アジャイルから遠ざかるかもしれない。でも、口頭のコミュニケーションを好むと、必要な人に情報を広めるのにもっと労力が必要になるかもしれない。

書面と口頭のメリデメを踏まえてバランスを取りましょうという話。心しておきたい。

- 7.7.6　使用上の注意

- > 中間ドキュメントを書くのをやめるには、XPのプラクティスに厳格でなければならない。
- ですよね。

- その他
> http://www.jamesshore.com/v2/blog/2008/the-documentation-myth
> ドキュメンテーションの神話
2008年9月2日
The Art of Agile DevelopmentのDocumentation practiceについての解説です。
>
> アジャイル開発の大きな神話の1つは、アジャイルチームは自分たちの仕事を文書化しないというものだ。結局のところ、アジャイルチームはドキュメントを壁に投げつけるよりも対面での会話を好むし（会話の方がはるかに効果的だ）、メンテナンス用のドキュメントをプロジェクトの最初よりも最後に書くことを好む（手戻りが少なく、最新の状態であることが保証される）。
>
> しかし、根底にはある神話があります。それは、ドキュメント作成のやり方が悪いという非難に伴う激しい怒りや思い込みに反映されています。その神話は、それほど無害なものではありません。それがこちらです。
>
> > **神話**：ドキュメンテーションは良いものである。
>
> 人々はいつもこの神話にとらわれています。これは、彼らの思考プロセスにおける根本的な欠陥を反映しています。彼らは「（このライブラリ、システムアーキテクチャ、このツールは何のためにあるのか）理解するのに苦労している」と考え、しばらく頭を叩いた後、開発者とその近視眼的なドキュメントの欠如を呪うのです。
>
> これはプログラマーの普遍的な経験であり、すべてのプログラマーは "ドキュメントの存在 "が "コードの質 "と同じであると推論します。そして、それからの数年間、書くものすべてに10行のコメントブロックを追加して過ごすのですが、（幸いにも）10行の定型文は何の付加価値もないことに気づくのです。
>
> しかし、ほとんどのプログラマーは、論理的に次のステップに進むことができません。コメントブロックが品質を向上させないように、いや、むしろ品質を悪化させてしまうように、同じことが単なるドキュメンテーションにも当てはまります。ドキュメンテーションは必ずしも良いものではありません。それは神話なのです。
>
> では...良いものとは何か？私たちがドキュメントに目を向けるとき、本当は何を求めているのでしょうか？答えです。
>
> 当たり前のことを言って申し訳ありません。しかし、ドキュメントが欲しいのではなく、答えが欲しいというように考え方を変えると、すべての視点が変わります。ドキュメントは、目的を達成するための手段であり、特に良いものでもありません。説明させてください。
>
> > **現実**。答えは良いものです。
>
> ...そして、その答えをより早く得ることができれば、それに越したことはありません。
>
> - 例えば、コメントを必要としないほど名前が付けられ構造化されたコード、直感的に使用方法がわかるソフトウェア、すべてのAPIコールから目的と使用方法が叫ばれるライブラリなど、質問をする必要がないことが最高です。XPでは、これを目指すべき理想として提唱しています。確かに達成するのは難しいです。確かに達成するのは難しいですし、いつもそこに到達できるわけではありません。でも、やってみて、ドキュメントが必要だと思ったら、もう一度やってみてください。
> - 次に良いのは、誰かに質問をしてすぐに答えてもらえることです。電話やメールでも、相手の反応が早ければ問題ありませんが、スピードとコミュニケーションの質において絶対的に優れているのは、すぐ隣にいる人が質問に答えてくれることです。夢物語ではありません。このような即応性があるからこそ、アジャイル手法ではクロスファンクショナルチームやコロケーションチームが重視されるのです。生産性の向上は素晴らしいものです。
> - それほどではありませんが、それでもかなり優れているのは、答えを簡単にググれることです。エラーメッセージをGoogleに入力して「検索」を押すと、500人もの人がその問題を経験し、すぐに使える答えを提示してくれることがあります。すごいですね。
> - そして、リストの一番下にあるのが、"ドキュメントを読んで答えを見つける "ことです。確かに、ドキュメントが美しく整理され、素晴らしく書かれていて、読むのが楽しいこともあります。そうですね。しかし、それ以外の場合は、そうではありません。そして、答えを得るまでに読まなければならないドキュメントが多ければ多いほど、あなたの立場は悪くなります。ドキュメントが多いことは良いことではなく、その逆なのです。膨大な量の情報（The Almighty Thud）で唯一素晴らしいのは、その音です。
>
> 次に、誰かがコメントの不足やドキュメントの不足について文句を言っているのを聞いたら、その人をちょっと止めてみましょう。彼が本当に不満に思っていることは何でしょうか？コードが不明確なのか？ライブラリの構成が不完全なのか？それらの問題を解決してください。もしかしたら、何も問題がなくて、ドキュメント神話に屈しているのかもしれません。