開発ドキュメント自動化：GitHub連携から修正案の確認まで

開発ドキュメント自動化は、コードから文書の下書きを作り、その後の変更に関係する説明を見つける作業を助けます。GitHub連携では、どの変更がどの説明に影響したのかを確認できることが重要です。

最初に接続する文書

一つのリポジトリと、よく使うAPIガイド、ローカル実行手順、アーキテクチャ説明から始めましょう。コードと照合できる文書が適しています。製品の意図や運用経験はコードだけで確定できないため、人が補う情報として分けます。

GitHub連携の手順

1. リポジトリへのアクセスを確認し、必要な範囲だけ許可します。
2. Specifyの文書プロジェクトにソースを接続し、作成する文書を選びます。
3. 生成結果を実装と照合し、実行コマンド、パス、リクエスト例を確認します。
4. コード変更後は関連文書と修正案を確認します。接続成功だけで全ての文書が更新されたとは判断しません。

GitHubはpushやpull requestなどのイベント別にWebhookを提供しています。受信するイベントは連携設定によります。GitHub公式文書を参照してください。

変更例を確認する

決済APIのstatusがpayment_statusに変わったと仮定します。フィールドだけでなく、レスポンス例、エラー処理、呼び出し側の例も確認します。これは説明用の例で、顧客の実績ではありません。各修正案について変更点、根拠、人が判断する部分を確認してください。

自動反映の範囲

Specifyの新規プロジェクトは自動反映なしで開始します。その後はプロジェクト設定と適用ポリシーに従い、許可された低リスク変更が自動承認される場合があります。処理時間は規模や文書範囲で変わり、全てのコード変更で修正案が必要になるわけではありません。

範囲を広げる前に

根拠を特定できるか、パスと実行例が正しいか、確認担当と反映方針が決まっているかを確認しましょう。

機能紹介またはワークスペース開始へ。API文書の更新とオンボーディング文書の生成も参考にしてください。