> For the complete documentation index, see [llms.txt](https://livlog-llc.gitbook.io/engineering-handbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://livlog-llc.gitbook.io/engineering-handbook/handbooknoto/16-handbook-writing.md).

# 16. Handbookの書き方

Livlog Engineering Handbook は、一度作って終わる文書ではありません。

プロダクトや開発方法の変化に合わせて、少しずつ更新していきます。

## 書くときの基本方針

* 推測で書かない
* 事実と方針を分ける
* 古くなった情報は更新する
* 外部公開できない情報は書かない
* 読み手が次に何を見ればよいか分かるようにする

## 書いてよいこと

* 開発思想
* 技術方針
* プロダクト概要
* 使用している技術
* 公開済みのURL
* オープンデータ活用方針
* AIネイティブ開発の考え方
* 一般化できる運用ノウハウ

## 書かないこと

* APIキー
* パスワード
* 内部サーバー情報
* 非公開の顧客情報
* 個人情報
* 公開していない契約情報
* 推測で補った説明

## 文章の粒度

Handbookでは、細かすぎる手順よりも、考え方と判断基準を重視します。

詳細手順が必要な場合は、各リポジトリのREADMEやdocsに記載し、Handbookから参照します。

## 更新ルール

* プロダクトを追加したらプロダクト一覧を更新する
* 技術構成が変わったら該当ページを更新する
* 運用方針が変わったら開発運用方針を更新する
* 古い記述を見つけたら放置せず修正する
* 本文で新しい略語やリブログ固有の用語を使う場合は、用語集への追加または既存定義との整合を確認する

## AIを使って書く場合

AIを使って文章を作成する場合でも、最終確認は人間が行います。

特に、サービスの説明、公開日、URL、技術構成は推測で補わず、確認できた情報だけを使います。

## 更新時の確認

文書を更新したら、[公開前チェックリスト](/engineering-handbook/handbooknoto/16-handbook-writing/publication-checklist.md)に沿って、情報の正確性、公開範囲、読みやすさ、継続運用のしやすさを確認します。

あわせて、次のコマンドで目次への掲載、章番号、リンク、見出し階層、末尾空白を機械的に検証します。

```bash
python3 scripts/check_docs.py
```

チェックリストまたは機械検証で問題が見つかった場合は、変更を公開する前に修正します。