Difference between revisions of "Best practices"
(Add fields for IMCR guidelines) |
|||
Line 2: | Line 2: | ||
==Overview== | ==Overview== | ||
− | + | Below are a set of best practice (BP) recommendations for the IMCR. | |
− | == | + | |
− | + | ||
+ | ==Discovering software== | ||
+ | Recommendations for discovering software in the IMCR. | ||
+ | ===IMCR=== | ||
+ | Add recommendations here. | ||
+ | |||
+ | |||
+ | |||
+ | ==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=== | ===ESIP software assessment guidelines=== | ||
* [https://esipfed.github.io/Software-Assessment-Guidelines/guidelines.html ESIP Software Guidelines] | * [https://esipfed.github.io/Software-Assessment-Guidelines/guidelines.html ESIP Software Guidelines] | ||
+ | |||
+ | |||
==Publishing software== | ==Publishing software== | ||
− | + | BPs for publishing software in the IMCR and software repositories (e.g. GitHub). | |
+ | ===IMCR=== | ||
+ | Publishing in the IMCR is easy and requires information about how the software can be identified, understood, executed, as well as who to contact for support and how it's being developed and maintained. If you haven't published in the IMCR before we recommend using this guide to ensure the supplied metadata makes your software discoverable and understandable by the IMCR user community. | ||
+ | ====Identify==== | ||
+ | =====What is the software called?===== | ||
+ | =====What is a short description for this software?===== | ||
+ | =====What are general categories for this software?===== | ||
+ | =====Is there a project website for the software?===== | ||
+ | ====Understand==== | ||
+ | =====Who created this software?===== | ||
+ | =====Are there any additional contributors of note for this software?===== | ||
+ | =====What useful features of this software are worth highlighting?===== | ||
+ | =====(Optional) Who is the publisher of this software if not the author?===== | ||
+ | =====(Optional) How can a user get support for the software?===== | ||
+ | =====(Optional) Has the software been adopted in a project, organization or by a person?===== | ||
+ | =====(Optional) Is there any information about uses of this software?===== | ||
+ | =====(Optional) Are there any statistics of its use?===== | ||
+ | =====(Optional) Are there any publications where the software is used?===== | ||
+ | =====(Optional) Is there any benchmark information about the software?===== | ||
+ | =====(Optional) What are the funding sources for this software?===== | ||
+ | =====(Optional) What are the ratings for this software?===== | ||
+ | ====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=== | ===Project repository=== |
Revision as of 10:58, August 2, 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
Add recommendations here.
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 and requires information about how the software can be identified, understood, executed, as well as who to contact for support and how it's being developed and maintained. If you haven't published in the IMCR before we recommend using this guide to ensure the supplied metadata makes your software discoverable and understandable by the IMCR user community.
Identify
What is the software called?
What is a short description for this software?
What are general categories for this software?
Is there a project website for the software?
Understand
Who created this software?
Are there any additional contributors of note for this software?
What useful features of this software are worth highlighting?
(Optional) Who is the publisher of this software if not the author?
(Optional) How can a user get support for the software?
(Optional) Has the software been adopted in a project, organization or by a person?
(Optional) Is there any information about uses of this software?
(Optional) Are there any statistics of its use?
(Optional) Are there any publications where the software is used?
(Optional) Is there any benchmark information about the software?
(Optional) What are the funding sources for this software?
(Optional) What are the ratings for this software?
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.