What is a publishable tutorial?
Tutorials are articles that take users through specific tasks or sequences of tasks to help the users learn how to do these tasks on their own for other applications or purposes.
Tutorials are accompanied by associated other materials which help the reader put into practice the calculations described by the tutorial.
These additional materials may include
- web pages with walkthroughs or instructional materials and downloadable files to work with
- a website with training information and downloadable Jupyter notebooks teaching users how to perform a modeling task
- a more extensive online course-like format with recorded lectures.
Tutorials must involve only software that has been previously validated through one or more peer-reviewed publications, and those must be referenced in the presubmission letter. Often, one of the software developers will be a tutorial author. In some cases, other users will have sufficient expertise to provide the highest-quality tutorials expected for LiveCoMS. If no developer is a proposed author of the tutorial, the presubmission letter should provide sufficient argument why the authors’ expertise is right for the tutorial.
Scope of tutorials: Tutorials should endeavor to cover a specific task or set of tasks at hand with explicit instructions, rather than cover too much information in a less detailed manner. However, they should also highlight how the steps might need to be modified, or additional care might need to be taken at particular points, to handle more general cases.
The scope of the tutorial, as well as the expected proficiencies / outcomes for researchers who complete the tutorial, should be clearly defined.
Prerequisites for tutorials: Tutorials should clearly define what concepts or abilities researchers will need to complete the tutorial (e.g., some proficiency in Python; experience with Jupyter notebooks; knowledge of classical MD; etc).
Tutorials should clearly define what system and/or software requirements the researcher will need to complete the tutorial (e.g., VMD version 1.9 or newer, AMBER, etc.). Tutorials requiring specific software packages must provide instructions and files for the referenced version of the software, as well as any information that might affect the output (e.g., what precision the binaries were compiled, what machines they were compiled on). As mentioned above, the software must have beeen previously published and validated, as the goal of a tutorial is not to introduce newly-developed software but to facilitate others’ using an established piece of software to carry out a particular task.
Pre-existing tutorials: The submission of existing tutorials, so long as they meet the journal standards described here, is explicitly welcomed. Our goal is to encourage the development of high quality tutorials by providing some degree of academic credit for these important and time-consuming efforts.
Additional criteria considered in the review of tutorials
- Are files and necessary executables required to run the tutorial posted online in a permanent (or nearly so) way?
- Are the tutorials suitable for the intended audience (e.g., researchers with only basic knowledge or advanced researchers)?
- Do they include enough information on how to generalize the approach to handle other cases, and highlight major issues to consider?
- Do the tutorials use commonly agreed on best practices?
- Do the tutorial authors clearly provide, where possible, information (e.g., primary literature citations) about why particular choices are being made during the step-by-step process?
- Does the tutorial require use of proprietary software or data? If so, are workarounds made available for reserachers who may not have access to such software or data?
Revision schedule for tutorials
Authors should generally update tutorials as the software involved changes; these tutorials are expected to be kept functioning and if they do not, they may be indicated as out-of-date on LiveCoMS’ site.