galaxyproject / galaxyproject/training-material

Inaccuracies and inconsistencies in hands-on sections in NGS Data Logistics Tutorial

Open
#2,420 0 comments 2 reactions 0 assignees View on GitHub
CoFest introduction newcomer-friendly paper-cut
Dominant language
HTML
Stars
367
Forks
1.1k
Avg merge
16h 27m
Merged PRs (30d)
49

Description

There are multiple minor inaccuracies in the hands-on sections of the NGS data logistics tutorial. Nothing erroneous, but inaccurate and/or inconsistent that makes it harder to follow, especially for a novice. Overall, compared to other tutorials, the steps seem to be less thoroughly described, with some key details glossed over. Being an introductory tutorial, I think it's important that its hands-on sections are explicit and precise. Here are a few examples:
- While some sections include a last step "Hit Execute; This will produce [description of files]", others don't. (which raises doubts: did I miss a step? Or is this informational only?)
- There are no specific file renaming instructions for produced datasets; however, subsequent steps refer to renamed files. In most cases, there's a helpful explanation (`output_paired_coll (output of fastp tool)`), but in some the explanation is not quite so helpful: (`output (Input dataset)`: what input? there were many.)
- The "single dataset" icon next to the input dataset field name is incorrect in most cases: it should be a "dataset collection" icon (unless I am wrong?)

Contributor guide

Open the contributing guide

Research direction

Review the hands-on sections of the NGS data logistics tutorial, comparing their execution instructions and dataset references with the other tutorials. Document which steps need explicit Execute guidance, dataset renaming instructions, clearer input descriptions, and corrected dataset or collection icons; done means the sections are consistent and precise for a novice.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.