・ビジネス上の要件
・自分のところのAPIはどう振る舞うべきか
・どうしてそう決めたか(ちょっともとの要件からねじれてる)
・中はどう作るべきか
を、全部一箇所に書くのは結局無理でした。
なので
・ビジネス上の要件
・自分のところのAPIはどう振る舞うべきか(の、一段階抽象化したやつ)
だけを書いて
・どうしてそう決めたか → こうすれば「想定されてるケース全部うまくいくから亅で逃げる
・本当のAPIの振る舞い → 別に書いたテストで表現
・どう作るか → 上のテストが通れば何でもいいよ
という体裁に。
俺が伝えるべきことは伝えられるドキュメントになったと思うけど、
俺は一体何屋なんだ(笑)