Digital documentation

An initial overview and how-to on the GBIF Secretariat’s new system for producing, publishing and maintaining up-to-date documentation for data publishers and data users

To strengthen key skills, GBIF needs to develop and maintain a comprehensive set of clear reference information and training materials that support all GBIF audiences. Since 2016, the Secretariat has been upgrading documentation to deliver this comprehensive resource, first via concise explanatory text materials (including numerous translations by network members into French, Portuguese, Spanish, Chinese, Japanese and Russian).

Building on a set of recommendations proposed by VertNet, the GBIF Secretariat is developing an integrated workflow to produce, publish and maintain up-to-date, community-curated documentation for sharing and using biodiversity data from the GBIF network.

This effort will establish an open digital-first system for reviewing, prioritizing, updating and creating new documentation with the assistance of an editorial panel and peer-review process. The Secretariat’s 2019 work programme and budget has allocated €30,000 to commission two phases of work to produce high-priority guidance from subject-matter experts.

Technical resources will provide the additional detail needed by those working in specific areas like digitization, data publishing and use of GBIF-mediated data. The Secretariat will coordinate ongoing maintenance and updates to this curriculum with contributions and translations from the network.

The documentation will be written in AsciiDoc, a lightweight plain-text format that supports the structural elements needed to prepare and produce technical documentation using the same source content for both digital and print formats.

The Documentation Cookbook will reside at https://github.org/gbif/docs-cookbook.

Structural and naming conventions

Repositories for new documentation can be cloned from the template available at https://github.org/gbif/doc-cookbook. Cloning will set up the following standard file structure"

assets/
  data/
  table-1.adoc
  dataset.csv
  figure-1.pdf
images/
  _source/
    art-hirez.ai
  web/
    art.png
  photo.jpg
text/
  en.adoc
  es.adoc
  en/chapter-1/
    chapter-1.adoc
    readme.adoc
  es/capitulo-1/
    capitulo-1.adoc
    readme.adoc

The root folder contains the following documents (/* denotes required)

acknowledgements.adoc
citation.adoc*
contributors.adoc*
cover.adoc: front cover
epigraph.adoc
glossary.adoc: lexicon
index.adoc*: list linking to each language version
licence.adoc*: assert copyright/copyleft status
readme.adoc*: preface/introduction
summary.adoc*: table of contents
title-page.adoc*

One repo per document hosted in the GBIF GitHub directory.

Each repo is named with the prefix ‘doc-’, followed by a short, expressive name e.g.

doc-effective-nodes-guidance

Translations are organized in subfolders named by their respective two-letter language code.

Precedents