mersy note
2023/12/19
Tag : Document

ドキュメントに関する記事を読んでADRとか学びが多かった

プロジェクト内で自分の役割的に何かしらのドキュメントを書いたりすることが多い。
読まれることを意識しつつ、チームでやってく上では最低限必要だからという感じで用意しているが。。。

大分好き勝手やってる所もあるから、どの程度わかりやすくなっているのかは、、、、聞いてみないと何ともではある。

ちょうどこの3つの記事を読んで非常に参考になった。
記事として公開してもらってありがたい。

ADR を1年間書いてみた感想 - 一休.com Developers Blog
https://user-first.ikyu.co.jp/...

はADRというのを知れてよかった。
設計とかを書くときに、色々と判断したポイント、経緯があってドキュメントとして残っている。
その経緯をどう書いておくとわかりやすいのか？と思っていた。

書かれてあることだけをみればいい場面もあるのだけど、書かれていないことが気になって質問・確認が来たりすることがある。

検討済みであることを明記しておくいい方法はないモノか？と思ったので、ADRというのを少し取り入れていってみたい。
補足として経緯とかを書いておくことはあるのだけど、そうするとどうしても冗長になってしまっていて、後で読むのがツライ感じになりそうだなぁと思っていた。

Design Docs との棲み分けの話もかかれていたので参考になる。
意識して Design Docs を書いた事は無いのでこの辺もやってみたい。

社内技術ドキュメンテーションを科学する - スタディサプリ Product Team Blog
https://blog.studysapuri.jp/en...

はドキュメントに関係するようなことのつらさとかとかが本当にその通りと思った。

そもそもドキュメントが用意されていない、探せない。
簡単な箇条書きレベルでもいいとおもうのに決まった事などがまとまっていない、更新されていないといったことなどなど。

自分も完全にできているか？というと難しい所はあるけれど、案件毎に状況は全然違うし、なにか書いたらそこで終了ではなくて、プロジェクトのスタートしたときから終わりまでひたすら更新していくことになる。

最初から最後まで案件に携わっていると案件理解が一番あるから、案件理解が足りていない人のことを想像しづらくなる。
それがドキュメントの散在だったり、そもそも不足だったりに繫がるように思う。

スポットで参加した人とかがとりあえず見始めればいい場所が決まっていて、そこから情報も探索でき。
必要な時に検索すれば情報が見つかりやすい。
そんな感じの状況にしておければ良さそうな気はする。

1年かけてAnewsのドキュメントを改善した話 - Stockmark Tech Blog
https://tech.stockmark.co.jp/b...

はドキュメント作成文化、オーナーシップ、何を使って書くか？と言うところが参考になった。

Notion はいいサービスだとは思うのだけど、ドキュメント書くのはまだ慣れていない。。。
どういう人と共有するか？になるけど、完全に内部だけだったら bit part だと Docbase で済ませることが多いし。

発注元（うちの場合は制作会社が多いけど）と共有することが多いなら、 Google Docs / Spreadsheet をベースに進める事が多い。
Backlog とかがあってそこの wiki でやることもある。
場所はどこでもいいから、まず書く場所・書ける場所を決めてほしい、というのがある。

後で書こうと思うと大変になるから、確認が発生して回答もらった時点でそれは決定している内容なのだから、それはドキュメントとして残すべき内容になる。

「xxx文書」みたいな改まった文章である必要はないわけで、決定している事項を後でまた別の人が確認しなくてもいいように簡単に記載しておく。
確認の経緯はそこからリンクさせておく。
それでいいと思うのだけど、そういう情報を掲載しておく場所が先に用意されていることがあまりないイメージがある。
あった方がいいとおもうからこちらからは依頼していく形になるわけだけど。。。

誰向けにかくのがいいか？
どれが読みやすいか？
どれが探しやすいか？
どんなツールが使いやすいか？とか判断軸は多くてこれが正解とはいえないものだと思うのだけど。
小さなことでもいいから何かしらやっていこう。

ADRとか記事を読めて知ることができたけど、もっと本もよんで知識を仕入れないとだ。
知ってる範囲でしか考えられないわけだから、そこに広がりが無ければ今やっている事しかできない。