-
Notifications
You must be signed in to change notification settings - Fork 1
SOURCE: Digital documentation
EDIT, MINE AND UPDATE AS NECESSARY: INFO NOT CURRENT AS-IS
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.
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.