説明の書き分け
データセット・テーブル・列の説明と README に、それぞれ何をどの長さで書くかの規約
データセットについて分かったことは、データセット・テーブル・列の description と、リポジトリの README.md に書きます。説明は一覧や検索結果にそのまま表示されるので短く書き、詳しい解説は README に書きます。
書く場所と長さ
| 書く場所 | 書くこと | 長さの目安 |
|---|---|---|
データセットの description |
何のデータか、出典 | 1〜2 文と出典 1 文(100 字程度) |
テーブルの description |
1 行が何を表すか、間違えやすい点 | 概要 1 文(80 字程度)、空行、注意の箇条書き 3 個まで |
列の description |
定義、単位、コードの体系 | 50 字程度 |
README.md |
出典と利用条件、テーブル一覧、使い方の SQL、注意、テーブルごとの詳細 | 制限なし |
docs/*.md |
README に載せきれない解説(README からリンクする) | 制限なし |
テーブル一覧や検索結果には、テーブルの説明の最初の段落だけが表示されます。概要の 1 文で、そのテーブルを使うかどうかを判断できるように書いてください。
description: |-
市区町村別・用途別の着工建築物の数・床面積・工事費予定額(年次)です。
- 区の行と市の行が同じ列に並びます。絞らずに合計すると二重に数えます。
- 秘匿の値は NULL です。
原則: それが成り立つ一番小さい範囲に書く
書こうとしている文が真であるための最小の対象を選びます。
| その文が真なのは | 書く場所 |
|---|---|
| 1 つの列について | 列の description |
| 1 つのテーブルについて | テーブルの description |
| 複数のテーブルにまたがって | README の「注意」 |
| そのデータセットの呼び名について | keywords |
| SQL として実行できる | README の「使い方」か docs/*.md |
小さい方に書いたら、上には繰り返さないでください。同じことを 2 箇所に書くと、片方だけが直されて食い違います。
間違えやすい点は、まずデータの形で無くす
説明に注意を書く前に、テーブルや列の作りで間違いを防げないか確認します。
- 粒度の違う行が混ざる → テーブルを分ける
- 5 桁のコードしか無い → 6 桁の全国地方公共団体コードの列も持たせる
- 年がずれる値が並ぶ → 列名で区別する
説明に残すのは、秘匿や収録範囲のように元データに由来して変えられない点です。
説明に書かないもの
- 検証の数字(「全国計と一致」「不一致 0」): dbt のテストか README に書きます
- ライセンスの全文:
licensesと README の「出典と利用条件」に書きます - 加工の手順やビルドの手順: 利用者向けでない保守の手順は
MAINTAINING.mdに書き、README からはリンクしません - 実行できる SQL: README の「使い方」か
docs/*.mdに書きます
README の構成
README はデータセットのページに、テーブル一覧の下に表示されます。次の順に書くと、他のデータセットと同じ形で読めます。
# データセット名と、何のデータかを 1〜2 文## 出典と利用条件: 出典へのリンクと利用規約## テーブル: テーブル名・内容・行数の一覧## 使い方: そのまま実行できる SQL の例## 注意: 複数のテーブルにまたがる注意## スキーマ.テーブル: テーブルごとの列・粒度・注意の詳細## 更新: 手元でビルドするコマンド
リポジトリの docs/*.md は、README からリンクしているかどうかにかかわらず、データセットのページの「ドキュメント」タブに一覧で表示されます。テーブルが多く README が長くなるときは、テーブルごとの詳細を docs/*.md に分けて README から目次としてリンクしてください。
文体
説明も README も、です・ます調の普通の文で書きます。用語は「データセット」「テーブル」「列」「バージョン」に統一してください。
列名と日本語名
列名と title の決め方はデータセットの規約にあります。
keywords
keywords は検索の索引に入ります。分類する語だけでなく、そのデータを指す別の呼び方も入れてください。利用者が正式名称を知らなくても検索で見つけられます。
keywords: [統計, 人口, 社会, e-Stat, 政府統計, 社会・人口統計体系, SSDS]
テーブル固有の語はデータセット側ではなく、そのテーブルの keywords に置きます。
迷ったときの確認
- テーブルの説明の最初の段落は 1 文で、そのテーブルを使うかどうかを判断できるか
- その文は、書いた場所より小さい対象について言えないか
- 同じことを 2 箇所に書いていないか
- 注意を書く代わりに、テーブルや列の作りで防げないか
- 説明に SQL・検証の数字・加工の手順が混ざっていないか
- 別の呼び方が
keywordsに入っているか - 新しい列名が
data_elements.csvのaliasesにある省略形になっていないか
