ドキュメントをたくさん書く

株式会社iCARE では技術系のドキュメント共有に Kibela を利用しています

ドキュメントの維持はコストがかかるので最低限にしたいのですが、同時に必要なドキュメントというものもあります。開発を優先しているとドキュメンテーションはどうしても後回しになりがちです。また、質が高く劣化しにくいドキュメントを書くのにも技術が必要です

お気持ちドキュメントを書く

実装から少し離れた視点で長期的な方向を見るためにお気持ちを表明しています。これらは、日々の実装で厳しさの片鱗を見つけたり、日々の会話の中でフロントエンドに限らずエンジニアメンバーが感じているもやもやなどからネタを見つけて、「どうありたいのか」「なぜそうなのか」「ここを気にするといいかも」といった点を重点的に書いています

• graphql の現状とスキーマ駆動に向けてのロードマップ

• ECR活用による開発体験の向上

• Vue3化ロードマップ

• フロントエンドのエラーハンドリングを Sentry で加速しよう

• etc.

実装向けドキュメント書く

ぼくが直接コードを触るのは基本「全体の仕組み部分」「メンバーが困ったことのトラブルシュート」「ペアプロ」なんですが、その時に行った対応が全体で共有してものになる事が多く、そういった場合は自分でドキュメントを書いたり、対応したメンバーにお願いしてドキュメントを書いてもらったりします

仕組みのドキュメント

ビルドの仕組みやライブラリの仕組みなど、ソースコードを読み解かないといけない部分や、自分たちの関わっているアプリケーションで特有の注意点などは、具体的なコードではなく広めの視点で全体像を解説するようにしています

• フロントエンドのリントについて

• webpack の仕組みについて

• etc.

HOW-TO のドキュメント

特にライブラリやフレームワークは汎用性が高く、自由度高く活用することができます。ルールで縛ることはしませんが、ベースとしてこうあるといいな、はドキュメントにしています

• CSS についての現状と辛みと方針

• 共有コンポーネントの Storybook の記述方法

• graphql の useQuery を使いこなす / apollo-client のキャッシュについて

• etc.

トラブルシューティング

難し目のトラブルシューティングで簡単には解決できなさそうなものもドキュメントにまとめています。こちらは具体的なコードを使い、「どこで発生したのか」「なにが原因なのか」「どうやって調べたのか」「どうやって解決したのか」をまとめて、読んだ人が「なぜ」に辿り着けるように、を意識したドキュメントにしています

• 動的に Buefy を利用した時に useTranslate がエラーになるときの対処法

• bulma のパッチを適用する

• GraphQL における日付のサーバサイドの実装について

• etc.

みんなでドキュメントを書こう

もうひとつ重要なのはメンバーにドキュメントを書く習慣をつけてもらう、ということです。プライベートなドキュメントを書く習慣ができている人は多いですが、共有用のドキュメントを書くのは自信がなかったり、そもそも何を共有するべきかが判断できない場合が多いです

すこしずつでも慣れてもらえるように、ペアプロや定例のタイミングで「これブログに書いてみたら？」「これ記事にまとめて定例で共有してよ」などと促しています（ iCARE のエンジニアのすごいところはこういうアドバイスをした時にすぐに実行するところですね。アドバイスのしがいがあります）

ドキュメントが充実していくと、何かあった時にさっとリンクを共有することでスムーズに解決できたり、場合によってはメンバー同士が「あそこに書いてあったよ」などの会話が生まれます。ドキュメントが不要なコードを書くことと両輪で、品質の高いコードベースを保っていきましょう

---

この記事は iCARE の技術顧問がどんな事をやっているか - 2021アドベントカレンダー の13日目の記事です