この記事はLITALICO Advent Calendar 2022のカレンダー2の16日目の記事です
https://qiita.com/advent-calendar/2022/litalico
はじめに
LITALICOでエンジニアをしている @tomoki-oke です。早いもので入社して4年目になりました。
気付けば担当プロダクトの開発チームでは長くいる方になっており、仕様やコードについて新メンバーに説明する機会が増えてきました。口頭で説明するだけではなく、今後のためにも知識をドキュメント化していかねばと感じ始めています。
そんな中、今年担当プロダクトとSaaSをAPI連携する案件があり、それについての運用ドキュメントを書く機会がありました。
これまでドキュメント書きには苦手意識があったのですが、これまでと書き方を変えてみたところ、納得いく内容を書ききることが出来ました。
中身は割愛しますが、こういった構成のものを書きました。
この記事では今回ドキュメントを書くにあたり、試してよかったことを3つご紹介します。
ここでいうドキュメントは開発者がチームの保守運用のためにコードや仕様を説明するドキュメントを指してます。
試したこと
ドキュメントの対象読者を考える
この記事をとても参考にさせて頂いたので、これを引用する形でご紹介します。
📝メンタルモデルの有無や目的に応じてドキュメントをかき分ける
ドキュメントを読む人は様々です。そのツールを使い始めようとしている人、特定の使い方を探している人、100%使いこなしたいと思っている人、などなど。そういった読者に合わせたドキュメントを書くことが重要です。
これからドキュメントを読むユーザーは一概に開発者といえども、事前知識が全くない新メンバーかも知れませんし、機能拡張のために実装の詳細を知りたいメンバーかも知れません。
読者によって事前知識の量や欲しい情報は異なっているので、誰が読む想定なのか・その人は何を知りたいのか、を考えるのが大事なんですね。
ドキュメント書きの難しさは「なにを書くのか考えること」にあると思うんですが、この作業を挟むことで書く内容の方向性をはっきりさせることができました。
また対象読者を明確にすることで、自分の中で「このドキュメントは将来マジで役に立つ」と思えるようになり、モチベーションが高まりました
参考までに、今回自分はSaaSのAPI連携のドキュメントを書くにあたり、この記事のJasperのドキュメント構成を参考に以下3種類のセクション（読者）に分けました。
-
概要: 新メンバー向け。SaaS自体の説明とAPI連携のかんたんな説明 -
状況別対応マニュアル: 運用者向け。運用で問題が起きたときの対応マニュアル -
リファレンス: 開発者向け。実装の詳細に踏み込んだ話
もくじから考える
中身を書く前に全体の構成をざっくりと箇条書きで考えておきます
もちろん書き進める中で足りてない項目に気付いたりしてどうせ変更は加わるので、軽く考える位がちょうどいいです。
最初にもくじを考えておくと書きたい内容を網羅しやすくなりますし、全体構成の枠があることで失速しがちな終盤も、悩まず書き進めやすくなると思います
もくじが出来たら、その段階でチームメンバーに見てもらえるとなお良いです。この時点で中身は書いてないので書くつもりの内容は補足しつつ、ドキュメント全体の方針をレビューしてもらえると、書ききった後に修正するよりも手戻りが少なく済むはずです。
コード同様にレビューしてもらう
書き終わったらメンバーへのお披露目です！当たり前かもしれませんが、書いて終わりではなく、やはりドキュメントもレビューしてもらうのがいいです
チームメンバーからしてもドキュメントに記載されてる内容をキャッチアップする機会になるので、そういう意味でもレビューを挟むのが良いと思います。
おわりに
「マジで役に立つだろうな」と思いながらドキュメントを書くのは、結構楽しいものでした。
ドキュメント書きもプロダクト作りと同じく喜ぶユーザー（読者）のことを考えれば、ちょっと楽しくなれる気がします！
楽しく役に立つドキュメントを作っていきましょう
明日は @nonsaito さんが担当します。お楽しみに 最後まで読んで頂きありがとうございました！