Difference between revisions of "Best practices"

From Earth Science Information Partners (ESIP)
Line 64: Line 64:
 
List the funding sources for the software (i.e. grant name, funding source, and grant award number). Add multiple funding sources with the "+" icon.
 
List the funding sources for the software (i.e. grant name, funding source, and grant award number). Add multiple funding sources with the "+" icon.
 
=====What are domain specific keywords for this software? (e.g. hydrology, climate)=====
 
=====What are domain specific keywords for this software? (e.g. hydrology, climate)=====
Do not add domain specific keywords to this field, they are not currently searchable. Instead add them to the field "What are general categories (keywords, labels) for this software?" located at /Locate/Important. Use the [http://vocab.lternet.edu/vocab/registry/index.php IMCR Controlled Vocabulary] to keyword your software with science domain specific keywords (see the "science domain" category of the IMCR CV). Keywords are the primary mechanism by which users find your software. Add broad terms and narrower terms to improve search and discovery. Be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to the IMCR chairs.
+
List science domain specific keywords to this field and to the field "What are general categories (keywords, labels) for this software?" located at /Locate/Important. Use the [http://vocab.lternet.edu/vocab/registry/index.php IMCR Controlled Vocabulary] to keyword your software with science domain specific keywords (see the "science domain" category of the IMCR CV). Keywords are the primary mechanism by which users find your software. Add broad terms and narrower terms to improve search and discovery. Be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to the IMCR chairs.
 +
===== (Optional) Is there any similar software that you know of?=====
 +
Add URLs or DOIs of similar software.
 +
===== (Optional) What are the recommended uses and assumptions of this software?=====
 +
Describe recommended uses and assumptions.
 +
===== (Optional) Are there any constraints on use, situations it is not designed for, simplifications?=====
 +
Describe constraints and non-supported use cases.
  
 
====Execute====
 
====Execute====

Revision as of 12:02, October 14, 2018

Return to IM Code Registry main page


Overview

Below are a set of best practice (BP) recommendations for the IMCR.


Discovering software

Recommendations for discovering software in the IMCR.

IMCR

To find software, use the IMCR Controlled Vocabulary in combination with the "Filter Software List" located in the IMCR Portal. Terms in the controlled vocabulary are organized around the data life cycle, which is an intuitive way to think about the different categories of information management. Browse the controlled vocabulary to identify terms you'd like to search on, then add these terms to the "Filter Software List" search tool to find what you're looking for. Some notes on the search tool:

  • Search only supports search across software names. Free-text searching is not supported.
  • Author supports search across software authors, including individuals, organizations and initiatives. Separate multiple terms with commas. An auto-complete drop down field lists software authors found in the IMCR.
  • Keywords supports search across keywords tagged to each software item of the IMCR. Browse the IMCR Controlled Vocabulary for a list of keywords and definitions.
  • Language
  • License
  • Operating System
  • Publisher supports search across software publishers. The content of "Publisher" is often times equivalent to content listed under "Author"

Developing software

No software development standards are enforced in the IMCR, however community recommended BPs are list below for anyone interested in learning and applying them.

ESIP software assessment guidelines


Publishing software

BPs for publishing software in the IMCR and software repositories (e.g. GitHub).

IMCR

Publishing in the IMCR is easy but some guidance on how to best supply information about your software goes a long way to helping others discover and reuse it. Below are recommendations for completing the form fields for your software registration in the IMCR.

Identify

What is the software called?

Enter the name of the software. Content in this field is not searchable, however the name of the software entered at the time of registering the software is searchable.

What is a short description for this software?

Add a brief description of the software (< 20 words). Content of this field is not searchable.

What are general categories (keywords, labels) for this software?

Use the IMCR Controlled Vocabulary to keyword your software. Keywords are the primary mechanism by which users find your software. Add broad terms and narrower terms to improve search and discovery. Be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to the IMCR chairs.

Is there a project website for the software?

Add the URL to where the software project is being developed/maintained or is downloadable.

Understand

Who created this software?

Add the project, organization, person, or initiative that helped create this software. You are encouraged to add multiple entities (i.e. organization and all individuals). For individuals, use given name and surname. Be careful to spell names correctly! Note, an drop down auto-complete field helps with this. The content of this field is searchable by the "Filter Software List" "Author" field.

Are there any additional contributors of note for this software?

Add major contributors to the software project. These entities can be of the same types listed under "Who created this software?" (i.e. project, organization, person, etc.). The content of this field is searchable by the "Filter Software List" "Author" field.

What useful features of this software are worth highlighting?

Describe some of the useful features users may want to know. This is a free text field, the content of which is not searchable.

(Optional) Who is the publisher of this software if not the author?

Add the project, organization, person, or initiative who published this software. Duplicate entries are encouraged from the "Who created this software?" field. The content of this field is searchable by the "Filter Software List" "Publisher" field. Separate multiple entries with commas.

(Optional) How can a user get support for the software?

Add a URL and/or email address to where a user can report bugs, request features, and extensions etc.

(Optional) Has the software been adopted in a project, organization or by a person?

Add a list of adopters and a brief description of how each uses the software (e.g. Environmental Data Initiative - Adopted by EDI's Data Curation Team)

(Optional) Is there any information about uses of this software (papers, research labs, etc)?

Add URLs or DOIs to information describing use of the software.

(Optional) Are there any statistics of its use?

List any metrics by which a user could assess use. These may include number of downloads, citations, or mentions.

(Optional) Are there any publications where the software is used?

Add the citation URL or DOI along with a full bibliographic entry for the cited entity.

(Optional) Is there any benchmark information about the software?

Describe how your software compares to other similar software.

(Optional) What are the funding sources for this software?

List the funding sources for the software (i.e. grant name, funding source, and grant award number). Add multiple funding sources with the "+" icon.

What are domain specific keywords for this software? (e.g. hydrology, climate)

List science domain specific keywords to this field and to the field "What are general categories (keywords, labels) for this software?" located at /Locate/Important. Use the IMCR Controlled Vocabulary to keyword your software with science domain specific keywords (see the "science domain" category of the IMCR CV). Keywords are the primary mechanism by which users find your software. Add broad terms and narrower terms to improve search and discovery. Be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to the IMCR chairs.

(Optional) Is there any similar software that you know of?

Add URLs or DOIs of similar software.

(Optional) What are the recommended uses and assumptions of this software?

Describe recommended uses and assumptions.

(Optional) Are there any constraints on use, situations it is not designed for, simplifications?

Describe constraints and non-supported use cases.

Execute

What is the URL for the code?
What license is the code released under?
(Optional) Is there a URL for the executable?
Is there any on-line documentation about the software?
What language(s) is the software written in?
What operating system can the software run on?
How can one install the software?
What other software does the software require to be installed?
(Optional) Are there estimates of how long it takes to run this software on average?
(Optional) Are there any memory requirements for this software?
(Optional) Are there any other important details about the implementation of this code?
Is there any test data available for the software ?
(Optional) Are there any specific instructions for testing the software?

Do Research

What input files does the software require?
What are the input parameters used for this software?
What output files does the software produce?
(Optional) Are there any relevant data catalogs that can be used with this software?
What other software can interoperate with this one?
(Optional) Is this software typically used with other software in a workflow?
Is there a preferred publication or citation for this software?

Get Support

What is the e-mail contact for this software?
What is the support offered for this software?

Update

(Optional) How is the software being developed or maintained?
(Optional) Are there any on-line resources for accessing the developer community for this software?
What versions does the software have?

Project repository

Considerations for features to include in the project repository.

README

README are essential for orienting the user to what the project addresses.

Vignette

Vignettes are useful for demonstrating the projects functionality.

DOI

Periodic releases of the project code can be accompanied by the minting of a DOI. GitHub supports archive in with generation of a DOI, thereby making the project citable.

Test data

Test data facilitates experimentation and understanding of the projects functionality.

Tagging

Tagging the project repo with good keywords facilitates discovery. See the IMCR Controlled Vocabulary.