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"
The root folder contains the following documents (/* denotes required)
cover.adoc: front cover
index.adoc*: list linking to each language version
licence.adoc*: assert copyright/copyleft status
summary.adoc*: table of contents
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.
Translations are organized in subfolders named by their respective two-letter language code.