From fc1d8ee94842a141a3837136c350dfe0abe3c1bc Mon Sep 17 00:00:00 2001 From: larnsce Date: Tue, 27 Oct 2026 14:29:32 +0100 Subject: [PATCH] docs(guidebook): point the build chapters at the FAIR Data Publishing guide The guidebook keeps the chapters only pkgreview owns: the PII and sensitivity check, the publication floor and what review looks like. The scaffold, dictionary and publication chapters become one pointer paragraph each to the guide at openwashdata/fair-publishing, which owns the build instructions, so no two documents carry the same steps (openwashdata/washr#85). README and NEWS follow. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_0154SimLT4PMoMfR91HPbiy9 --- NEWS.md | 1 + README.md | 2 +- docs/guidebook.md | 24 +++--------------------- 3 files changed, 5 insertions(+), 22 deletions(-) diff --git a/NEWS.md b/NEWS.md index 48b2b9b..1f75c6d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -14,6 +14,7 @@ The release that pairs with washr 1.2.0. The check script takes its metadata, do - `/create-release` runs a preflight with a remedy per check; NEWS.md is maintained per review PR and renamed at release; `dev` gets the development version after the DOI sync, in `/add-doi` Step 9; release post outline under `references/templates/` (#55). - `/create-release` and `/add-doi` commit `.zenodo.json`, which washr 1.2.0 writes with the citation files. Zenodo reads it from the release tag for the resource type, the community, the creators, and the license (openwashdata/washr#56). - Dictionary round trip (#37, Part 2): passes with `washr::update_dictionary()`; descriptions and extra columns such as `unit` and `allowed_values` survive a data change. Recorded in `docs/roadmap-v1.1.md`; #38 and #39 are unblocked. +- Guidebook reduced to the chapters only pkgreview owns (PII and sensitivity, the publication floor, what review looks like). The scaffold, dictionary and publication chapters point to the FAIR Data Publishing guide (openwashdata/fair-publishing), which owns the build instructions (openwashdata/washr#85). # pkgreview 1.6.1 diff --git a/README.md b/README.md index 82cb5d1..e9580fe 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This repository provides a structured review workflow for R data packages in reg The review standard has two tiers. Required items are the publication floor: a package is not published until every required item passes. Advisory items are quality improvements; the reviewer may fix them or record them as optional follow-ups, and they never block publication. The tier of every item is recorded in the checklists under `skills/pkgreview-core/references/checklists/`. -Creating a data package for one of the registered organizations? Start with the [contributor guidebook](docs/guidebook.md). It covers the PII and sensitivity check to run before committing data anywhere, the publication floor, the dictionary, and what review and publication look like; for the scaffolding steps it points at the washr Get started vignette. +Creating a data package for one of the registered organizations? Start with the [contributor guidebook](docs/guidebook.md). It covers the PII and sensitivity check to run before committing data anywhere, the publication floor, and what a review looks like. The build steps themselves are in the [FAIR Data Publishing](https://openwashdata.github.io/fair-publishing/) guide and the washr vignette. ## Quick Start diff --git a/docs/guidebook.md b/docs/guidebook.md index 5b42f1e..008923b 100644 --- a/docs/guidebook.md +++ b/docs/guidebook.md @@ -21,7 +21,7 @@ The check also covers your git history. A column you added in an earlier commit ## 2. Scaffold the package with washr -The [washr](https://github.com/openwashdata/washr) package sets up the whole structure, from the raw data folder to the website, and each function tells you what it created and what to do next. Follow the washr [Get started](https://openwashdata.github.io/washr/articles/washr.html) vignette for the steps in order; the narrative version with the reasoning behind each step is the [data publishing guide](https://global-health-engineering.github.io/ghedatapublishing/). Package names are lowercase, short, and descriptive of the data, e.g., `waterpointdata`. If you work with Claude Code and have the pkgreview skills installed, `/washr` runs the same steps with you: it calls the washr functions in order and drafts the descriptions and the README text for you to confirm. It needs washr 1.2.0 or newer, and it never replaces your own check of every description. +The [washr](https://github.com/openwashdata/washr) package sets up the whole structure, from the raw data folder to the website, and each function tells you what it created and what to do next. The build steps are not repeated here. Follow the guide [FAIR Data Publishing](https://openwashdata.github.io/fair-publishing/) for the full walkthrough with the reasoning behind each step, or the washr [Get started](https://openwashdata.github.io/washr/articles/washr.html) vignette for the condensed version. Both follow the same order as the review areas below. ## 3. The publication floor @@ -59,19 +59,7 @@ Folders and the processing script: `data-raw/` holds the raw data exactly as you ## 4. The dictionary -The dictionary is the file `data-raw/dictionary.csv`. It has one row per variable, and the one-sentence description per variable is the most important part of the whole package. A reader who has never seen your project should understand what a variable means from its description alone. - -A good description says what was measured, in plain language, with the unit if there is one: - -- Good: "Distance in meters from the household to the nearest water point." -- Good: "Whether the water point was working on the day of the visit (yes or no)." - -A bad description repeats the variable name or stays vague: - -- Bad: "The distance variable." -- Bad: "Status." - -Write or confirm every description yourself. A generated description that nobody checked does not meet the floor, because the review standard requires a human to confirm each one. +The dictionary is the file `data-raw/dictionary.csv`, with one row per variable and a one sentence description per variable that a person wrote or confirmed. It is the most important part of the whole package, and a generated description that nobody checked does not meet the floor. How to write the descriptions, with examples of ones that work and ones that do not, is in the guide chapter [Preparing the data](https://openwashdata.github.io/fair-publishing/data_preparation.html#write-the-data-dictionary). ## 5. What review looks like @@ -88,10 +76,4 @@ You stay the maintainer of your package. The review is help, not a takeover. ## 6. Publication -After the review, the package is published: - -- A GitHub release is created from `main`. -- The release is archived on Zenodo, which assigns a DOI (a permanent identifier that makes the dataset citable). -- The DOI goes into the citation files, the README badge, and the website metadata, so the citation in the README and on the website shows how to cite your dataset. - -After publication, your dataset has a website, a DOI, and a citation, and anyone can install it as an R package or download the CSV files. +After the review, the package is released from `main`, the release is archived on Zenodo, which assigns a DOI, and the DOI goes into the citation files, the README badge and the website metadata. The steps are in the guide chapter [Creating a release and a DOI](https://openwashdata.github.io/fair-publishing/creating_doi.html). In a review, the reviewer runs them with the `/create-release` and `/add-doi` skills. After publication, your dataset has a website, a DOI and a citation, and anyone can install it as an R package or download the CSV files.