ドキュメンテーションツールの導入

2021年12月12日 10:41

ぼくが関わり始めた 2020年10月ころはフロントエンドエンジニアはまだ5人程度だったのが、今では15人を超えて一気に3倍に増えました

人数が増えてきて問題になるのがコード品質のばらつきです。マネージャー陣もすべてのコードの把握はできませんし、関われる時間が限られた技術顧問ではなおさらです

また、これまで実装されたコードもあまり明示的な共有はされておらず、それぞれが思い思いに共通化していたため車輪の再発明が大量に発生していました

ちょうどいいタイミングということで、共通で利用するコンポーネントとモジュールを対象としてドキュメンテーションツールの導入を行いました

storybook に addon-docs を導入する

さいわい 6系の storybook がすでに導入されていたので addon-docs を導入して、コンポーネントの「 props 」「 event 」「 slot 」などにコメントを書いて共有できるようにしました

また、このタイミングで開発環境にデプロイしたらそのブランチの Storybook を閲覧できるように Rails を拡張して、エンジニア以外とのコミュニケーションにも活用できるように

昨日のデザインシステム始めましたでも触れましたが、ちょうどデザインシステムの導入も進んでいたタイミングだったので、ブラウザを通して会話ができる一助になっていると思います

コンポーネント以外の共通コードのドキュメンテーションとしては TypeDoc を採用しました。これは TypeScript の型定義を参照して適切なドキュメントを生成してくれるツールになります

ドキュメントの鉄則は「可能な限り書く項目を少なくする」という方針でこちらを採用。一部、モジュール周りの仕様に不満があったので typedoc-plugin-merge-modules というモジュールを導入しました（詳しくは： TypeDoc v20 でファイル分割されたモジュールをいい感じにまとめて表示する - Qiita ）

ようやく環境は整ってきたのですが、これを有効に活用できるかはこれからです

まだまだちゃんとドキュメント化できていない共通モジュールもたくさん残っていますし、そもそも共通にするべきなのに個別のページで実装されているコードがたくさん存在するのでそれらの整理も必要です

さいわい新しいメンバーもみんな優秀なので、共通化についてはレビューなどで声がけしながら、少しずつ整理されたコードベースに向かっていけていると思います