3  Documenting the data

The dictionary describes the variables. This chapter turns it into help pages, completes the description of the package as a whole and generates the machine readable metadata that dataset search engines read.

3.1 Write the help pages

Every dataset in an R package has a help page. washr writes its source from the dictionary:

setup_roxygen()

This creates one file per dataset under R/, with a title placeholder, a description placeholder and the variable table from the dictionary, written as roxygen comments (lines that start with #').

Open each file and replace the two placeholders. The title is a human readable name of the dataset, on one line. The description is a brief statement of what the dataset contains and what it is for. Then add a @source line above the quoted dataset name at the end of the file. It names who collected the data, a URL or a reference, and the date you accessed it. For a data package, the source is the most important field of the help page after the description.

The lines from @format to the closing brace are generated from the dictionary. Do not edit them. When a description changes, change it in the dictionary and run setup_roxygen() again. It regenerates only the variable table and keeps the title, the description and the source you wrote.

Then build the help pages, check the package and install it:

devtools::document()
devtools::check()
devtools::install()

devtools::document() writes the help pages to man/. devtools::check() runs the same check as the workflow on GitHub. A warning about the license is expected at this point and goes away in the next section. devtools::install() installs the package on your computer, so that the README and the website can load the data.

Commit and push.

3.2 Complete the DESCRIPTION file

DESCRIPTION describes the package as a whole, with its title, what it contains, who made it and under which license. The citation files, the README, the website and the metadata all read from it, so a value that is wrong here is wrong everywhere. Fix it here and never in a generated file.

3.2.1 Authors

Add yourself as author and maintainer:

usethis::use_author(
  given = "Your First Name",
  family = "Your Last Name",
  role = c("aut", "cre"),
  email = "your.email@example.com",
  comment = c(ORCID = "0000-0000-0000-0000")
)

aut marks an author and cre the maintainer, the person who receives questions about the package. The ORCID iD reaches the citation files, the Zenodo record and the metadata, so give it when you have one.

Add every other person who contributed with the same call, with role = "aut" for an author and role = "ctb" for a contributor. To collect the names, email addresses, roles and ORCID iDs, open an issue in the repository titled “Author information for DESCRIPTION” and ask everyone to add their line.

3.2.2 The fields washr writes

update_description()

The call sets the fields the review standard expects and keeps every value that is already there. It writes the language, the date, the repository and bug report URLs, which it takes from the repository named in DESCRIPTION, and the CC BY 4.0 license when the package has none yet. It also writes a few Config/washr/ fields, such as the funding sentence of the website and the analytics domain, with the openwashdata values for a package under openwashdata. The later steps read them from DESCRIPTION. The vignette section Publishing outside openwashdata explains how another organisation sets its own values.

Now open DESCRIPTION and write the title and the description. The title is one line in title case without a final period. The description is one paragraph that says what the data contains, where it comes from and when it was collected.

3.2.3 Keywords, coverage and source

Three facts have no other home and go into DESCRIPTION by hand. Add three lines with your own values:

X-schema.org-keywords: sanitation, faecal sludge, Kampala
X-schema.org-spatialCoverage: Kampala, Uganda
X-schema.org-temporalCoverage: 2022-03-01/2022-09-30

The keywords are a comma separated list. For an openwashdata package, start with open data and washdata, then add the topic and the country or region. The spatial coverage is a place name. The temporal coverage is the first and the last date of the data, separated by a slash.

When the data comes from a published article, add its DOI as well:

X-schema.org-isBasedOn: https://doi.org/10.2166/wh.2026.173

The citation files then cite the article next to the data package, and the metadata records it as the source. Several DOIs are separated by commas.

Run devtools::document(), devtools::check() and devtools::install() again, then commit and push.

3.3 Generate the metadata

One function derives the machine readable metadata of your package from the files you have already written, which are DESCRIPTION, the dictionary, the citation file and the exports in inst/extdata/.

update_metadata()

It writes a schema.org description of the dataset as JSON-LD into pkgdown/templates/in-header.html. The website build in the next chapter embeds it in the head of every page, where dataset search engines such as Google Dataset Search read it. The function ends with the fields it could not fill and where to fill them. Before the release, the DOI is the one field that stays blank.

Nothing in this file is edited by hand. When a value is wrong, change its source and run the function again. Run it again after every change to DESCRIPTION, the dictionary or the exports, and once more after the DOI exists (Chapter 5). A second run with nothing changed writes nothing.

Commit and push.