ドキュメント作成の歴史的変遷
こんにちは ソフトウェアエンジニアの三長です
こんにちは ソフトウェアエンジニアの博多家です
ゆるテクは三長と博多家が緩く技術の話をするポッドキャストです
よろしくお願いします
よろしくお願いします
はい じゃあ 今日はホストが私なので
私がまず話を振って進めていこうと思います
今日用意した話題は
最近私が所属しているエンジニアの組織で
自分たちの組織に抱えている課題のディスカッションをやる機会があったんですよ
もちろんいろんな立場だとかいろんなチームの方々が参加されるので
課題って結構人それぞれのところがあったんですけれども
すごく多かったテーマとして知識の継承というか
の課題が多くて その中でもよく見るよく出てきたキーワードとして
ドキュメント作りっていうキーワードが出てきたので
ぜひ博多家さんと今日は今までどんなドキュメント作ってきましたかねとか
こういうドキュメントあったら便利でしたとか
こういうものを作った時は逆に大変でしたみたいなエピソードがあれば
2人でワイワイしたいなと思ってます
はい
じゃあ話していきましょうかね
はい
ちょっと話したのは私なので最初に少し話をさせていただくと
私結構そのドキュメントって自分の仕事の仕方によって
だいぶ定義というかこういうものを作らなきゃいけないって思ったものが増えてきててですね
例えば新人の頃というか受け売りとかで仕事をしてた時期があったんですけれども
そういうタイミングだとやっぱドキュメントって言われると
だいたい基本設計書とか詳細設計書とか
データベース定義書とかそういう結構システム開発によく出てくる
キーワードのものがメインだったんですけども
だんだんチーム開発をするようになって
かつチームが長期間存続する継続するようになってくると
もちろん今言ったようなドキュメントって必要になってくるものもあると思うんですけども
もっと大事なのって背景がわかるようなドキュメント
なぜこれを作ったのかであったりとか
なぜこの技術を選定したのかとか
そういうものが残っていかないと後から入る人であったりとか
技術がどんどん進化していく中で
自分が後で見返すってことを考えた時に
めちゃめちゃ苦労するなって思うようになったんですよ
はいはいわかります
ドキュメントの種類と必要性
なので結構その時代によって必要とされるドキュメントとか
厚く書いた方がいいドキュメントって変わってきてるなって思いました
そうですね
なんかこの辺はくたけさんどうですか
ドキュメントって言われてパッと思い浮かぶイメージとかって
どんなものがあります?
ドキュメントは今の自分だと
三田さんがおっしゃった最後の方におっしゃったような
デザインドックとかその経緯がわかるやつとかですね
なぜこれをやるようになったのかとか
逆になぜこれを使わなかったのかとか
とは単純な仕様的なドキュメントも含みますかね
設計書みたいなものですか?ちょっと違いますかね
設計書ですね、仕様がこの機能はこういうことができるとか
そういった作るためのドキュメントですね
なるほどな、じゃあ結構あれですかね
今のそのドキュメントのイメージは
もしかするとここ二人の間では割と近しいものがある
そうですね、システム開発の話をしている時に
あんまり詳しくなくノーコンテキストでドキュメントって言われたら
そういう辺をイメージしそうな気はしますけど
考えたら他にもいっぱいありますよね
手順書、ランブックと言われそうなやつとか
他にもあるといえばありますよね
他にもたくさんあるにはあるので
それ全部作ってたらめちゃめちゃ時間かかりそうじゃないですか
作るのもかかるしメンテも大変ですよね
生きたドキュメントにしなきゃいけない
しておかないとあんまり意味がなくなってしまうので
そういったメンテで苦労したとか
逆にこういうふうにやるとめちゃめちゃメンテできてますとかって
エピソードあります?
悲しいことにあんまりないですね
自分はドキュメント結構両極端目な経験しかないかもしれません
はいはい
最悪にいたんですけど
そこではもうね、それこそ外部設計書から内部設計
自分が一番よく書いたのが詳細設計書と言われるような
いわゆる作るためのやつ
確かに
あとデータベース定義書とか画面繊維図とか
なんかもうとにかくめっちゃ書かなきゃいけないんですけど
でもあんまりメンテされないんですよね
わかります
めちゃめちゃわかります
メンテする時間がないから
こんなに作っても日本語読まないしなみたいな
ドキュメントの信頼性と重要性
コードが正しいみたいな感じで
確かによく技術の調べ物をするときに
きっちり公式ドキュメント読めるかどうかみたいなところで
差が出るみたいな記事を読んだことがあるんですけど
ただ実際自分が何かこう引き継いだものがあったときに
あんまりドキュメントしっかり読んでないなって思ったりしますね
確かにな
設計書どうだったかなとか
そこに書いてあることがあんまり信用できるものではないって
経験から学習しちゃったんでしょうねきっと
確かにおっしゃる通りですね
こう書いてるけど出力違うじゃんとかありますもんね
そうそうやっぱ動いてるものしか信用できないみたいな
だから結構いわゆるウェブ系みたいなところに今もいるんですけど
今の職場は結構ドキュメント書いてる方かななんですけど
そんなにでもやっぱりSIRの時ほどは書いてなくて
ドキュメント作成ツールの分類と利用
あんまりそうですねコード以外のドキュメントはそんなに
意見を交換するためのドキュメントとかは書きますけどね
GitHub Issuesとかでこういう風な設計にしようと思うけどみたいな
デザインドックみたいなもんですね
なるほど
ちなみにデザインドックしかりそういう何でしょうね
他に出てきたドキュメントもそうなんですけれども
結構ツール何を媒体に書いてたとかってあります?
使うツールって大きくその2つぐらいあると思ってて
いわゆるドキュメントツールともう一個が
図を書くためのツールってあると思うんですよ
そうですねMiroとかそういったとこも入るんですかね
Miroはそのあれだと思います
その2つが混ぜ合わさったツールだと思います
ドキュメント管理の課題と失敗事例
例えば書くとか
書くとか有名なところはDraw.ioがありますよね
確かに確かに
あの辺とかが図で
ドキュメント設計とかを書くようなやつだと
自分が多かったのはGoogle Docsとか
昔はWordとか
はいわかります
ウェブ系に来てからEssa.ioっていうサイトがあって
ナレッジツールみたいなのがあるんですけど
その辺は使った経験が長いですかね
なるほどな
じゃあ結構その商用のツールとか使って
管理することが多かったみたいな感じですかね
そうですねバックログとか
伊佐川さんも多分使ってるかな
そうですね
機械のツールはいろんなものがありますよね
実はそういうツールを使っていて
1回というか現在進行形で失敗してるところがあるんですけど
失敗というか痛い目を見てるところがあってですね
私結構好きなのって
履歴が残るであったりとか
レビューがしやすいっていう観点で
ドキュメント作るというか使うの好きなんですけど
例えばデザインドックとかは
マークダウンで書いて
基本Git管理するとか
はいはいはい
するとプルリクエストで自分が書いたデザインドック
これどうですかねって相手にお願いしやすいですし
っていうところは割と逆に上手くいったなって思ってるところで
失敗したのがそういう何て言うんでしょうね
そういうドキュメントツールが乱立とまでは言わないんですけど
いくつか選択肢が出ちゃったんですよね
はいはいはい
チームによってどこに書くかが
まちまちになってしまって
検索性が恐ろしく悪くなったっていうことはあります
分かりすぎる
自分もあります
そうなんですよね
後になって考えればそんな検索性のことを考えたら
ツール統一しておくのが
統一というかある程度決めておくのがもちろんベストじゃんって
今思えば間違いないんですけど
なぜ当時そういうことをやってしまったんだろうってなってます
でもあれじゃないです
やっぱり向き不向きがあるから
例えばデザインドックとかは履歴がやっぱ欲しい
Git管理するのはとても履歴がなってるんですけど
はい
じゃあ例えばエンジニア以外の人が見るドキュメント
更新もするドキュメントとかって
ちょっとGit管理に向かないわけじゃないですか
おっしゃる通りです
ドキュメント作成の理想像
だから用途がたとえ同じでも
使う人が変わってしまうとやっぱりツールが
使い勝手を最優先させると散らばらざるを得なくなり
はい
っていうのはやっぱありますよね
まさにおっしゃる通りでした
その当時も確か
マークダウンを書くのが全然苦じゃない方々もいらっしゃいましたし
ちょっとマークダウンで書くと圧倒的に作業効率が悪くてとか
っていう方々もいらっしゃって
おそらく別れちゃったんだと思うんですよね
なるほど
そこってもしかするとというか
将来的なことを考えた場合に
どっちかを習得するっていう選択も視野に入れた上で
やったほうがよかったんじゃないかとかは
次こういう場面に出くわしたら
その選択を取ろうかなと思ってます
いや難しいですよね
これは統一は自分は
なんかその統一もそうだし
ドキュメント管理全般
はい
あんまりその成功している職場というか現場を見たことがない気がします
確かに私も今まで
すごくうまくいってるなってあんまり見たこと
ちょっとドキュメントって表現すると抗議すぎるんですけど
見たことない気がしますね
そうですね
少なくともやっぱりドキュメント管理ツール
そのナレッジツールみたいなやつと
そのやっぱりバグトラッカーみたいなやつ
とかでなんかもう分散しちゃいそうな気がするんですよね結構
しそうですね確かに
その2つはどうしても分散してしまいそう
むしろ一定のじゃあ例えば分散を受け入れたとして
ドキュメントを作るっていうものの
理想の姿ってどういうものなんですかね
例えばまずそのドキュメントがしっかり保守されていることもそうでしょうし
あとはそのプロダクトの暗黙値と
多分形式値のバランスがめちゃめちゃ良くなってるとかも
そうなんですよねきっと
そうですね
どこまでいったらその私たちしっかりドキュメントコントロールできてるねってなるんだろうって
全然実はビジョンがなくてですね
結局でも読む時のそのインターフェースというか
ドキュメント作成に向けたペルソナの定義
そのやっぱりヒューマンリーダブルというか
人間に優しければいいと思うんですよ
かつ読む人によって読みたいシーンが多分違う
例えばエンジニアだったらコードを書きながら
ここって何でこうなってるんだろうっていうのをそのまま検索できればいいわけですよねきっと
でもなんかこう
マーケティングの人とか
だと何だろうなぁ
何か他の画面を見ながら
マーケティングツールとかを見ながら
ここはこういう
何でこういう数字になってるんだろうとかっていうのを調べられたりしたらいいかもしれないし
そうすると今のその白卓さんの話を聞いてると
やっぱドキュメントに応じてきっと
ペルソナが全然違っていて
そのペルソナごとにきっとユーザーストーリーマッピングというか
あとユーザージャーニングがあったりとかしてて
本気出して作るなら
ドキュメントを書き始めるタイミングで
そこの定義を明確にすることが大事そうですよね
そうですね
GPT-4の可能性について
誰向けなのかとか
どういう時に使われることを想定しているとか
賞味期限とか
とかとか
いろいろありそうですね
そうするともうドキュメント作るのも
一種のプロダクトってわけじゃないですけど
作りに近しいものありません?
あのと自分は思って
これあれなんですよ
最近和訳されたやつあるじゃないですか
Docs for Developersの
なんだっけエンジニアのためのドキュメントライティングみたいなやつ
なんかみたいなやつ
多分あれに同じようなこと書いてる気がするんですけど
多分自分がDocs for Developers読んだのすごい前なんで
忘れちゃったけど
多分そんな読む人のことを考えるとか
ドキュメントもプロダクトみたいなもんだぞみたいなことは
確か書いてあった気がするんですよね
けど本当につい最近になって自分は
それこそチャットGPTが出てきたので
確かに
あれに全部食わせたら解決なんじゃないのって思うんですよ
確かになんか全部食わせて
なんとなくこういうこと知りたいんだけどって言ったら
分析していい感じに答え出してくれんじゃないのって
そういうことです
新しいっすね
なんか分かんないですけど
セキュリティというかコンプライアンスというか
その辺の問題によって多分ないと思うんですけど
企業内のドキュメント全部とコードベース全てと
なんかチャットとかの履歴とか全部
とにかくあらゆる文章を全部放り込めば
確かに
全部の業務を知り尽くして
コードの隅まで分かっている
そこにNullageBSが出来上がると思うんですよね
それすごい
しかもあれですよねAPIとかも一応公開されてるから
そうそうだからコードを書きながら
それこそ分かんないけど
RaycastとかAlphaleteとかそういう系のやつとかで
シュッてここってこういうことって聞いたら
答えが書いてくるのは普通にできそうですよね
確かにそれなんかちょっとプライベートに開発で
遊んでみようかなって思えるぐらい面白そうですね
なんかどなただったかな
Scrapboxのめちゃめちゃ文章を書いてる方で
それをChat.CPと繋げて
なんかすごい第二の自分みたいな人が
回答してくれるみたいなことをしてたって
記事を見た気がします
データ加わせて人格構成させてるみたいな感じですね
そうですよね
いいですね
そうすると今の話でいけば
おそらく検索性の部分とかは
大幅に改善されるような気がしてて
あとはやっぱりその保守性とかですよね
そっちですね
今日知ったんですけど
GPT-4ってやつが出たじゃないですか
え、何ですかそれ初めて聞きました
あれ、Chat.GPTは3.5かなだったんですけど
4っていうのが出たんですよね
お金を払ったらだったかな
画像も食わせることができるだったらしいです
すごい
とか他のも多分いろんなことがあるんでしょうけど
ちゃんと見てないですけど
なんかBingChatだったっけなっていうのがあって
Bingってあるじゃないですか検索エンジンの
あれのAI版みたいなやつがちょっと前に出てたんですけど
あれの裏がそれだったらしいんですよ
そうなんですね
で、Bingってあれを出してくれるんですよ
ソース元
何とかって何?って聞いたら答えを返してくれて
ソース元はこのサイトですみたいなのを返してくれるんですよ
え、すごいあまり使ったことないからそれだけでも驚く気なんですけど
なんかだから、お、それはすごいなと思うとともに
あれですね
さっき言ったような使い方をもし社内ドキュメントみたいなのをしたら
ソース元返してくれそうじゃないですか
確かに
で、なんか分かんないですけどもっと進化したら
そこは間違っててこうだからこう書き直しといてって言ったら
まさか書き直してくれる未来が来ないのかなとか
来そう
もうセキュリティ面がでも後はどうなるかぐらいですよねきっとね
そうですね
なんか見えちゃいけないものが見えてしまって
それが検索できたらまずいですもんね
ドキュメント作成の設計
まずいですし、あとまあそこまでいったら人間がその聞いて何かをするっていう作業って本当にするのかなみたいなのはちょっとありますけどね
確かに
今の話を聞いていてあのめちゃめちゃ面白そうだなって思いつつ
そのドキュメントとかをドキュメントに限った話ではないんですけど
そういったところをどういう構成にしていこうかとかを設計するのって
私はすごく好きな方の人なので
もしそこまでやらなくてよくなったらめちゃめちゃ便利だなって思う反面
ちょっと楽しみが減ったなって思っちゃったりするかもしれない
わかる自分もそこが楽しいとこなのに
そうそう
奪われたって感じしますね
そうですよね
じゃあ次の楽しいもの見つけろよって言われればそれで全てなんですけど
まあ仕事を奪われるってこんな感覚なのかなって思っちゃいました
そうですねなんかつまんないこうなんか単調な作業でもAIがやってくれるのか
なんか面白いとこが取られて
泥臭いところが残るみたいな感じになりそう
それはそれでたまにはそういうの欲しいなとか思っちゃうんですけどね
うん
なるほどな
はいありがとうございます
博多家さんと話してて確かにチャットGPTいいなって思ったので
プライベートで触ってみようかなと思います
なんか自分はやっぱ結構怖いですけどね
そんな考えていくと
いやマジで置き換えられてしまうなっていうのはあるな
これあれですよねどういうふうにAIを使っていくかを考えないと
マジでいろいろ今できていること自分ができていることって置き換えられていきそうですよね
そうなんすよねというのは頭でわかってるのに
さっき三沢さんと話したかといって今AIにやらせてすごくいろいろできそうなところは
自分がやりたいんだよっていう気持ちなんですよね
わかりますわかります
だからあんまりなんかやる気になれないみたいなこの矛盾がちょっとあります
確かにそのめちゃめちゃ学習されてスクラムマスターとかできるようになっちゃったとしても
自分でやりたいなって思っちゃいますもん
わかるですよね
エピソードの終了
ですです
なるほどはいそんなところでちょっとドキュメントの
ドキュメントの話だったら怪しいところはありますが
ドキュメントについてちょっと2人で話してみました
じゃあ年度末ということで今日はそろそろにしようかなと思います
はいということでまあいいや
はいではですね最後Twitterではハッシュタグゆるテクをつけてツイートお願いします
ボロボロですね今日は
でGoogleフォームからも感想コメントをくれるようになっていますのでよろしくお願いします
お願いします
今日はありがとうございました
