プロダクトに対するなぜをesaで集める
サービスは運用していくうちに、トレードオフをした結果だったり歴史的経緯だったり外部要因によったりで一見不思議な仕様が生まれたりする。
そういうものを途中から入った人が、頭ごなしに否定するのは幸せとはいえない。
ということでesaに↓みたいなテンプレートを作ってみた。
疑問に思ったことを書いて経緯をしってる人が答えるみたいな運用を期待している。
また回答がない記事を一覧表示できるよう、解答待ちリスト用リストを出すための記事を用意してテンプレートでそこにリンクを張るという工夫をしている。
どの機能/サービス? --- 疑問に思ったこと --- ソースコード --- (場所がわかれば。なおGitHubのリンクを貼るときは y を押してSHA1を指定してもらえると後々ズレが出なくてうれしいです) 理由 --- (可能であればコンフル/Slack/Backlogなどのパーマネントリンクも添えてください [解答待ちリスト用リンク](/posts/1000))
合わせて記事を収集するカテゴリに以下のようなREADMEも用意した。
ここは? === ○○を触っていて疑問に思ったことがあったら、この下に記事を作成してみてください。 疑問の原因、 **何故** そうなっているのかを残して後から参照しやすくしたいなと思います 書いて欲しいこと === (テンプレートにあるやつ) どの機能/サービスか --- リポジトリ名でもいいし、口頭で言われるサービス名でも可だし、「ほげほげ機能」とかでもOK とにかく他の人が見てわかるようにしてください 疑問に思ったこと --- ここが一番大事 「なぜ〜は〜〜なのか」みたいな文章になってるとよいと思う。 合わせて「普通だったら〜だと思うんだけど」的文章があるとなぜ?と思った理由がわかってよい。 たとえば 「なぜ○○は××なのか?」て書くより「なぜ○○は△△ではなく××なのか?」って書いたほうが、疑問に思った理由が伝わりそう。 ソースコード --- わかればでいいです。 GitHubのリンクを貼るときはショートカットキーの y を押してSHA-1形式のURLにして欲しい。 具体的にこの行ってのがあれば行指定もしてくれると。 理由 --- なぜそうなっているか?を書くところ 自分でわからないときは空欄にしておくなり文章を WIP にしておくなりしておくのがよさそう
ちょっとでも自分たちが触っているサービスのなぜを減らせるようにがんばりたい。