Improve this document

GBIF invites community members to contribute to, improve and maintain our digital documentation .

If you are a first-time user, please don’t let the code-developer vernacular of ‘branches’, ‘pull requests’ and ‘commits’ frighten you. Our use of GitHub, while squarely based on its technical capabilities, is equally important from an editorial perspective. The design and format of the materials we publish through this system aim to ensure that any guidance we prepare and commission is uniform, reliable, reusable, versioned and up-to-date. Your contributions are vital to achieving this.

How to contribute to this document as a peer-reviewer (tl;dr)

  1. Create a GitHub account.

  2. Read the documents

  3. See something? Say something by creating an issue

  4. Follow and support the conversation

Best practices for community peer-reviewers

  • Recognizing that members of our community are all extremely busy, if you intend to provide comments during the community peer-review process, set aside sufficient time to read and digest the document (the PDF version of each document offers a convenient tool for this purpose).

  • Use a first read to form a general impression of the document, noting any major problems or concerns.

  • Keeping your notes handy, begin a second read-through in which you flag possible issues point-by-point.

  • Comment on the validity of the guidance provided in the documentation, identifying possible errors and evaluating the approaches

  • Identify any references, citations, precedents or examples that you feel may be missing or mischaracterized

How to submit your review comments and suggestions

  • If you have not already done so, sign up for a GitHub account. Again, to encourage transparency, choose a username that allows others in the community to identify and recognize you with relative ease.

  • Find the GitHub repository for the document under review. The HTML version of any document provides a link to “Edit on GitHub” and its source repository near the top of its tree navigation. Reviewers can also search for the repository through the GBIF GitHub organization page. Searches can be more efficient knowing that the names of the repositories for GBIF’s digital documentation all begin with the prefix doc-, followed by a shortened, plain-language version of the title.

  • Submit your comments as issues in the document’s GitHub repository. The ‘Issues’ tab is second from the left in every repository.

  • Where possible, group similar comments in a single issue. For example, reviewers who identify (heaven forbid!) multiple spelling or punctuation errors should consider submitting such items in a single issue. Then, when commenting on content or offering other suggestions, the same reviewer should include those in a second issue.

  • Use deep links to document sections. Reviewers can link to any section heading in any document, thereby providing an accurate citation of where the issue or problem you wish to identify arises. Mousing over the left end of the heading will cause the appearance of a section symbol—§—which users can then right-click or option-click to copy a direct link to that location in the document. The link available by right- or option-clicking the section symbol in the example pictured below, for example, is

    https://docs.gbif.org/effective-nodes-guidance/1.0/en/#_suggested_citation

  • Track the progress and resolution of your issues. We encourage you to sign up for notifications of actions that others take in connection with the issues you submit. Doing so may permit direct, reciprocal discussion between authors and reviewers, as and where appropriate.

What are we looking for?

Community review

By maintaining each document’s source text in a public GitHub repository, or ”repo”, community members have ready access to this material. Each time a new draft document is completed, we will ask members of relevant GBIF communities of practice (the intended users and beneficiaries of these documents) to offer direct input and feedback. The effect of this process is two-fold: to ensure the quality of the documentation and to foster community discussion and collaboration. Read more about the community review process.

Content issues

We encourage reviewers and users to help improve this document by offering comments, suggestions and corrections at any stage in its life cycle. In short: if you see something, say something.

Improvements can take any number of forms, but your suggestions should aim to:

  • make the document more coherent, consistent, or readable

  • add missing information

  • correct factual errors

  • fix typos

  • bring it up-to-date

In general, we ask that you create an issue when for your suggestions and corrections.

You can also use issues to highlight more technical, less editorial matters, such as errors and bug reports, recommendations on usability and formatting or suggestions on additional topics for us to consider covering in our documentation.

Be sure that you are logged in to your GitHub account if you have one—and if you don’t have one, please consider creating one. By doing so, you can ensure transparency and openness in the community peer-review process, enable authors to ask you about or clarify the issues you raise, track the progress of your suggestions and make certain that GBIF can properly credit your contributions.

What are we not looking for?

We use GitHub to manage the source material of our documentation openly to encourage community members to help us maintain it and keep it up-to-date. While we welcome your suggestions on such topics, the peer-review process should focus on the content of any given document rather than less editorial issues like the documents’ technical set-up and configuration, code or security issues. If you have issues you would like to raise on such matters, please contact us at communication@gbif.org.

Credit

GBIF will give proper credit and acknowledgement of community members who participate in the peer-review process. While this may initially take the form of a curated list of contributors, we are committed to improving these processes, particularly where the use of persistent identifiers like ORCID IDs can efficiently record community members’ activities and automate the production of annual reports and metrics.

Licensing

All GBIF digital documentation is licensed under Creative Commons Attribution-Share Alike 4.0 International. As a result, you are free to share and adapt it provided that you a) give appropriate credit, link to the license and indicate if changes were made and b) distribute your contributions under the same licence.

Code of conduct

All interactions in the GBIF community peer-review process must comply with GBIF’s Code of Conduct.