コンテンツにスキップ
Queria Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

説明の書き分け

データセット・テーブル・列の説明と 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. # データセット名 と、何のデータかを 1〜2 文
  2. ## 出典と利用条件: 出典へのリンクと利用規約
  3. ## テーブル: テーブル名・内容・行数の一覧
  4. ## 使い方: そのまま実行できる SQL の例
  5. ## 注意: 複数のテーブルにまたがる注意
  6. ## スキーマ.テーブル: テーブルごとの列・粒度・注意の詳細
  7. ## 更新: 手元でビルドするコマンド

リポジトリの docs/*.md は、README からリンクしているかどうかにかかわらず、データセットのページの「ドキュメント」タブに一覧で表示されます。テーブルが多く README が長くなるときは、テーブルごとの詳細を docs/*.md に分けて README から目次としてリンクしてください。

文体

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

列名と日本語名

列名と title の決め方はデータセットの規約にあります。

keywords

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

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

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

迷ったときの確認

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

このページは役に立ちましたか?