説明の書き分け

分かったことをカラム・テーブル・データセットのどの階層に書くかの規約

データセットについて分かったことを書ける場所は、カラム・テーブル・データセットの 3 階層あります。

どれに書くかを毎回考えると、実際には全部が 1 箇所に溜まります。Queria の e-Stat データセットは、6 スキーマ 30 テーブル分の注意が一番粗い階層に一塊で入っていました。意味ではなく長さで振り分けた結果です。

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

書こうとしている文が真であるための最小の対象を選びます。判断はそれだけで付きます。

小さい方に書いたら、上には繰り返さない。 上位に残るのは「複数を見比べないと言えないこと」だけになります。カラム説明に書いた話をデータセットの説明にも書くと、片方だけ直る日が来ます。

説明に入れる価値があるのは次の 5 つです。

4 と 5 は「読まないと間違える」種類の情報で、これが本体になることが多くあります。一番小さい範囲に降ろしてください。

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

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

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

実行できる SQL は説明に書かず、リポジトリの docs/*.md に置く使い方ガイドの原稿に書きます。説明は「読めば間違えずに済むこと」、ガイドは「そのまま動くもの」と分けてください。