---
title: 説明の書き分け
description: データセット・テーブル・列の説明と、README・ガイド・ドキュメントに、それぞれ何をどの長さで書くかの規約
---

データセットについて分かったことは、データセット・テーブル・列の `description` と、Markdown のファイルに書きます。説明は一覧や検索結果にそのまま表示されるので短く書き、詳しい解説は Markdown に書きます。Markdown は、データセットの概要（ルートの `README.md`）、テーブルのガイド（テーブルの Markdown の本文）、スキーマのガイド（`queria.yml` の `schemas` の `guide:`）、テーブルをまたぐドキュメント（`queria.yml` の `docs:`）の 4 つです。

## 書く場所と長さ

| 書く場所 | 書くこと | 長さの目安 |
|---|---|---|
| データセットの `description`（`queria.yml`） | 何のデータか、出典 | 1〜2 文と出典 1 文（100 字程度） |
| テーブルの `description`（フロントマター） | 1 行が何を表すか、間違えやすい点 | 概要 1 文（80 字程度）、空行、注意の箇条書き 3 個まで |
| 列の `description`（フロントマター） | 定義、単位、コードの体系 | 50 字程度 |
| `README.md` | 出典と利用条件、テーブル一覧、使い方の SQL、複数のテーブルにまたがる注意 | 制限なし |
| スキーマのガイド | スキーマの解説、テーブルをまたぐ SQL | 制限なし |
| テーブルのガイド（テーブルの Markdown の本文） | テーブルの使い方の SQL と注意 | 制限なし |
| `docs:` に並べたドキュメント | スキーマをまたぐガイド | 制限なし |

テーブル一覧や検索結果には、テーブルの説明の最初の段落だけが表示されます。概要の 1 文で、そのテーブルを使うかどうかを判断できるように書いてください。

```yaml
description: |-
  市区町村別・用途別の着工建築物の数・床面積・工事費予定額（年次）です。

  - 区の行と市の行が同じ列に並びます。絞らずに合計すると二重に数えます。
  - 秘匿の値は NULL です。
```

## 原則: それが成り立つ一番小さい範囲に書く

書こうとしている文が真であるための最小の対象を選びます。

| その文が真なのは | 書く場所 |
|---|---|
| 1 つの列について | 列の `description` |
| 1 つのテーブルについて | テーブルの `description` |
| 複数のテーブルにまたがって | `README.md` の「注意」 |
| そのデータセットの呼び名について | `keywords` |
| SQL として実行できる | そのテーブルかスキーマのガイド（[ファイルの置き場所](#ファイルの置き場所)） |

小さい方に書いたら、上には繰り返さないでください。同じことを 2 箇所に書くと、片方だけが直されて食い違います。

## 間違えやすい点は、まずデータの形で無くす

説明に注意を書く前に、テーブルや列の作りで間違いを防げないか確認します。

- 粒度の違う行が混ざる → テーブルを分ける
- 5 桁のコードしか無い → 6 桁の全国地方公共団体コードの列も持たせる
- 年がずれる値が並ぶ → 列名で区別する

説明に残すのは、秘匿や収録範囲のように元データに由来して変えられない点です。

## 説明に書かないもの

- 検証の数字（「全国計と一致」「不一致 0」）: dbt のテストに書きます
- ライセンスの全文: `licenses` と `README.md` の「出典と利用条件」に書きます
- 加工の手順やビルドの手順: 利用者向けでない保守の手順は `CONTRIBUTING.md` に書きます。`docs:` には並べません
- 実行できる SQL: ガイドかドキュメントに書きます

## データセットの概要（README.md）の構成

`README.md` はデータセットのページに表示されます。GitHub でもリポジトリのトップに表示されます。次の順に書くと、他のデータセットと同じ形で読めます。

1. `# データセット名` と、何のデータかを 1〜2 文
2. `## 出典と利用条件`: 出典へのリンクと利用規約
3. `## テーブル`: テーブル名・内容・行数の一覧。各テーブルの Markdown へリンクする
4. `## 使い方`: そのまま実行できる SQL の例
5. `## 注意`: 複数のテーブルにまたがる注意

テーブルごとの列・粒度・注意の詳細は、テーブルのガイドに書きます。

## ファイルの置き場所

テーブルの Markdown は `table:` でどのテーブルの説明かを決めるので、手元のファイル名と置き場所は自由です。ビルドするモデルの隣に置くと、モデルと一緒に直せます。ほかのドキュメントも手元の置き場所は自由で、何の説明かは `queria.yml` に書きます。

バージョンの中では、フォルダ 1 つが説明の対象 1 つです。ルートがデータセット、`<スキーマ>/` がスキーマ、`<スキーマ>/<テーブル>/` がテーブルです。各フォルダの `README.md` がその対象の説明で、同じフォルダのほかの Markdown がその対象の関連するドキュメントです。tabledoc は手元のファイルを次の場所に置きます。

| 書くもの | 説明する対象 | バージョンの中の場所 | 表示されるページ |
|---|---|---|---|
| `README.md` | データセット | `README.md` | データセットのページ |
| `docs:` に並べたファイル | データセット | ルート | データセットの関連するドキュメント |
| `schemas` の `guide:` のファイル | スキーマ | `<スキーマ>/README.md` | スキーマのページ |
| テーブルの Markdown の本文 | テーブル | `<スキーマ>/<テーブル>/README.md` | テーブルの「ガイド」タブ |
| Markdown がリンクする画像などのファイル | | 手元と同じパス | リンクした Markdown の中 |

```text
README.md                                   # データセットの概要
queria.yml
docs/
  catalog.md                                # スキーマをまたぐガイド（docs: に並べる）
  census.md                                 # census スキーマの説明（schemas の guide: に書く）
models/census/census_municipality.sql
models/census/census_municipality.md        # census.census_municipality の説明とガイド
```

この例では、`docs/catalog.md` は `catalog.md`、`docs/census.md` は `census/README.md`、`census_municipality.md` の本文は `census/census_municipality/README.md` に置かれます。

- 「ドキュメント」タブには、バージョンの中のファイルがフォルダの階層のまま並びます
- テーブルのガイドに列の一覧は書きません。列の定義は列の `description` に書き、テーブルのページの列一覧に表示されます
- ほかの Markdown へのリンクは手元の相対パスで書きます（例: `[市区町村別 基本集計](../models/census/census_municipality.md)`）。GitHub ではそのまま開け、バージョンの中では tabledoc が置き場所に合わせてリンクを書き換えます
- 2 つのファイルがバージョンの中の同じ場所に置かれるとき（`docs:` に同じファイル名を 2 つ並べたときなど）は、`tabledoc load` がエラーにします

## 文体

説明も Markdown も、です・ます調の普通の文で書きます。用語は「データセット」「テーブル」「列」「バージョン」に統一してください。

## 列名と日本語名

列名と `title` の決め方は[データセットの規約](/publish/conventions#列名)にあります。

## keywords

`keywords` は検索の索引に入ります。分類する語だけでなく、**そのデータを指す別の呼び方**も入れてください。利用者が正式名称を知らなくても検索で見つけられます。

```yaml
keywords: [統計, 人口, 社会, e-Stat, 政府統計, 社会・人口統計体系, SSDS]
```

テーブル固有の語はデータセット側ではなく、そのテーブルの `keywords` に置きます。

## 迷ったときの確認

- テーブルの説明の最初の段落は 1 文で、そのテーブルを使うかどうかを判断できるか
- その文は、書いた場所より小さい対象について言えないか
- 同じことを 2 箇所に書いていないか
- 注意を書く代わりに、テーブルや列の作りで防げないか
- 説明に SQL・検証の数字・加工の手順が混ざっていないか
- 別の呼び方が `keywords` に入っているか
- 新しい列名が `data_elements.csv` の `aliases` にある省略形になっていないか
