Need for basic documentation on usage of GBIF data

[gbif-portal]

Need for basic documentation on usage of GBIF data

Need for basic documentation on use of GBIF portal data download (and API)

First, the new portal feels and looks great, and is a big step forward, so I don't mean to sound too negative in the below, but this is an issue remark, right?

One thing that I feel that is largely forgotten in the new (and the old) portal is easy access to basic usage information. If the goal is to attract new user groups it should be possible to find, without enterprising into a google marathon, a clear and precise beginners guide to GBIF (and DwC). The IPT Wiki have some nice pages on what DwC is (https://github.com/gbif/ipt/wiki/DarwinCore.wiki), and also on how to publish occurrence, event and checklist data. At least I believe - I have seen those pages but can't find them on the fly again - which kind of illustrates the problem. This kind of information is maybe boring to the tribal community using the portal on a day to day basis, but it's absolutely needed in order for new user to get to that point without loosing interest. Possible user groups span widely in terms of technical know-how and background, although one must assume some basic knowledge on how to use a computer.

This does not need to be a very resource demanding thing to do. Again, there are wiki pages for the IPT, but not for using GBIF data. To be fair, the new portal does come a long way in this, and particularly the links on the tools/users tabs are easy to find.

For example, but by no means not limited to:

• DwC for dummies type of page (and / or a cheatsheet of the most important terms and what they means). Remember that one of the main obstacles to using (and to publishing, but that's not the topic for this issue) GBIF mediated data for new users is interpretation of the content and mapping to own data-models. DwC can be hard to get a grasp on, and although fine as a lookup for somewhat experienced users, the DwC quick reference guide will feel intimidating for someone jumping strait into it.
• A similar page and/or cheatsheet for the API. The API throws back a lot of terms that not are really explained (what is a nubKey?). I would believe that usage of the API will increase through tools like the rgbif package, and although you could argue that it's up to developers of these derived products to deliver documentation GBIF could be a bit more helpful by placing this information somewhere you can find it without detective work.
• Explanation of formats and technical sides of downloads. e.g. what is a Tab delimited .csv file and how do I open it in xl? (yes, I know the GBIF site should not teach basic computer usage, but at least a link to a relevant postings somewhere).

---

fbitem-67cbf865735ab20856e1e6649eab1c4073bc341e Reported by: anders.finstad@ntnu.no System: Firefox 51.0.0 / Ubuntu 0.0.0 Referer: https://demo.gbif.org/ Window size: width 1855 - height 923 API log&_a=(columns:!(request,response,clientip),filters:!(),index:'prod-varnish-',interval:auto,query:(query_string:(analyze_wildcard:!t,query:'response:%3E499%20AND%20(request:%22%2F%2Fapi.gbif.org%22)')),sort:!('@timestamp',desc))&indexPattern=uat-varnish-&type=histogram) Site log&_a=(columns:!(request,response,clientip),filters:!(),index:'prod-varnish-',interval:auto,query:(query_string:(analyze_wildcard:!t,query:'response:%3E399%20AND%20(request:%22%2F%2Fdemo.gbif.org%22)')),sort:!('@timestamp',desc))&indexPattern=uat-varnish-&type=histogram)

[kbraak]

Just to add, many others were in agreement with this proposal, brought forward yesterday during the NSG meeting.

[kbraak]

The following two handbooks can assist GBIF curate data sets it indexes and can help GBIF understand how to guide users in a) curating the data they download from GBIF.org and b) using it properly in accordance with data terms of use/license. Notably the second volume details steps a researcher might take to curate a data set from receiving the data to eventual reuse. It also contains a number of case studies Please see below:

Curating Research Data, Volume One: Practical Strategies for Your Digital Repository.

Volume One of Curating Research Data explores the variety of reasons, motivations, and drivers for why data curation services are needed in the context of academic and disciplinary data repository efforts. The following twelve chapters, divided into three parts, take an in-depth look at the complex practice of data curation as it emerges around us. Part I sets the stage for data curation by describing current policies, data sharing cultures, and collaborative efforts underway that impact potential services. Part II brings several key issues, such as cost recovery and marketing strategy, into focus for practitioners when considering how to put data curation services into action. Finally, Part III describes the full life cycle of data by examining the ethical and practical reuse issues that data curation practitioners must consider as we strive to prepare data for the future.

Curating Research Data, Volume Two: A Handbook of Current Practice.

Building from the introductory base established in Volume One.. the steps in Volume Two will detail the sequential actions that you might take to curate a data set from receiving the data (Step 1) to eventual reuse (Step 8). Notably, this handbook focuses on the data curation practices and techniques taken by curation staff in a digital repository setting, yet these steps will be valuable for anyone facilitating data management support for research data, regardless of the final destination of the data (e.g., long-term archiving). Therefore data curators, archivists, research data management specialists, subject librarians, institutional repository managers, and digital library staff will benefit from these current and practical approaches to data curation.

@dschigel @ahahn-gbif

[kcopas]

• [x] DwC for dummies type of page: see What is Darwin Core, and why does it matter?
• [ ] Page with starter tips for data users (add to download email)
• [ ] A similar page and/or cheatsheet for the API.
• [ ] Explanation of formats and technical sides of downloads. e.g. what is a Tab delimited .csv file and how do I open it in xl?

We're going to keep hearing that last one until we add more formats and/or label what we provide as .tsv (see latest https://twitter.com/ColinJCarlson/status/1023598320034480129)

[andersfi]

Thank's, the "what is Darwin Core" page is a great start!

A couple of points that I think could be added. E.g. what about providing a link in the download mail/download information witch resolves to a very short and basic information page witch has the main purpose of pointing the user to further information. There is a lot of resources out there, they are just a bit hard to find for those not fully assimilated into the tribe, technical documentation on format (what is the encoding, structure etc.. - this is actually quite important as opening a download file for the first time in e.g. R may require some guesswork and a lot of frustration before you get the details right). Also, there are several GBIF specific terms in the interpreted download file that is not DwC. Easy accessible "documentation" on this (e.g. speciesKey etc.) would be great.

Idea for the long run: whereas there is a great wiki on the IPT to help publishers, there is no similar resource to help the users of the data.

[dschigel]

@andersfi I really like your points, and clear documentation on data use is indeed a very needed improvement. I have in fact made a sketch of the data use guide some time ago, please let me know if you are willing to see the draft and revise TOC; you inputs on what should be there and not would be particularly valuable as you know the realities of GBIF and the data user world.