Pull Requestのフォーマットにビジネス文書のフォーマットを採用しようとしたが，失敗した話 - Lambdaカクテル

かつて，僕が所属しているチームではPull Request(以下PR)のフォーマット，特に「どうして変更するのか」「どう変更したのか」といった経緯などの要素があまり充実していなかった。このためエンジニアのみならずデザイナーやプランナーも含めたチーム内の意思疎通を潤滑にするために，適切なテンプレートを作成してそれに従おうというムーブメントがあった。 とはいっても「この形式が最強」みたいなものをインターネットに見出すことができなかったため，とりあえず『考える技術・書く技術』に範を取って「状況(今どうなっている)・複雑化(それを困難にしている新たな状況の出現)・結論(どうする)」というフォーマットを僕が導入してみた。 それ以前はカッチリしたテンプレートがなく，各自で「こういう感じなのでお願いします」という文言を考えていたので，PR作成者の負担を減らす効果をテンプレートに期待していた。 考える技術

[Windymelt]

知見求めています

[a-kuma3]

Gitに向いてない体質。PRってお願いじゃなくて、こう直した方が良いよね、という提案だから。フォーマットの問題じゃない。

[kwhrtsk]

これはおそらく技術文書を書くのが苦手なだけだと思う。PRの説明が下手な人はREADMEやコメント書くのも下手。必要なのはテクニカルライティングのトレーニング。それは全てのプログラマに必要なものでもある。

[atsushifx]

すでに言われていたが、文章を書く訓練が先。「達人プログラマー」でも言及されている

[Agrius_Akita]

門外漢だから放置して欲しいけど、この本なら４章の導入部の方が近いと思った。　状況(目的をしたい)・複雑化(この方法がある)・疑問(適切か)／状況(作業をした)・複雑化(依頼を受け作業をした)・疑問(結果はどうなった)

[ksugimori]

“なぜなら...” だと質問がオープン過ぎて答えにくいので「誰が困るのか？」「いつ困るのか？」みたいに具体的な聞き方の方が良さそう。/ 個人的には課題と解決案だけで十分な気がするけれど。

[akulog]

現職がこれに近いんだが、個人的にこういうの苦手なのでjsonで添付できるようにしたらどうか？とか思ったりする(やめろ

[hogashi]

めっちゃむずくて困っている/自分が書くときも気をつけている