こう
- 「設計書や
ドキュメントは、 何を、 どこまで 書きますか」 - 「ドキュメントが
古くなって、 誰も 読まなくなるのを どう 防ぎますか」 - 「なぜ
その 技術を 選んだのか、 半年後の 人に どう 伝えますか」
面接官が
- 書く
こと 自体が 目的ではなく、 チームや お客さんが あとで 困らないために 書く、と 分かっているか - 何を
書いて、 何を 書かないかの 線を、 自分で引けるか - 判断の
理由 (なぜそうしたか ) を 残す 大切さを 知っているか - 古くならない
仕組み (自動で 作る、 コードの 近くに 置く ) まで 考えているか
短い答え
- 全体の
構成図、 データの 形 (ER 図)、 API の 仕様、 大事な 判断の 理由の 4 つを 書きます。 - コードを
読めば 分かる ことは 書かず、 コードからは 読めない 「なぜそうしたか」を 残すほうが、 あとで 助かるからです。 - API の
仕様のように 変わりやすい物は、 コードから 自動で 作る 形に 寄せて、 古くならないようにします。
少し
書く 4 つ
- 構成図画面、
サーバー、 データベース、 外部の サービスが どうつながるかを 1 枚で。 新しく 入った 人が 最初に 読む物です - データの形表と
表の つながりを、 ER 図 (表を 箱、 つながりを 線で 描いた図) で - API の仕様 どの
住所に 何を 送ると 何が 返るか。 OpenAPI という 決まった 書式で 書くと、 そこから 説明の ページや 試す道具を作れます - 判断の記録なぜ
その 技術や 作りを選んだか
判断の
ADR (Architecture Decision Record) は、
# 0003 保存先に RDB を選ぶ
状況
注文と在庫を同時に直す必要がある
決めたこと
トランザクションを使える RDB
候補と捨てた理由
KVS は複数の更新をまとめにくい
引き換え
書き込みが増えたら分け方を考える半年後に
書かないこと
関数の
トレードオフ
書く
よく
- 全部を
細かく 書こうとする 書くのに 時間が かかり、 すぐ 古くなって 読まれなくなります - 何を
作ったかだけ 書き、 なぜかを書かない 理由が 無いと、 あとの 人が 変えて よいか 判断できません - コードと
同じ ことを 文書にも書く 片方だけ直されて、 どちらが 正しいか 分から なくなります
深掘りの問い
- 「ドキュメントは
どこに 置きますか」 コードと 同じ 置き場に 置き、 コードの 変更と 一緒に 直して 見直しを 通す、と答えます - 「ADR を
書くのは、 どんな 判断ですか」 あとで 変えるのが 大変な 判断 (データベース、 言語、 外部 サービスの 選び方 ) に 絞る、と答えます - 「古い
ドキュメントが 見つかったら」直すか、 消すか、 古いと 明記する。 間違った 文書は、 無いより 悪いと答えます