common-workflow-language / common-workflow-language/user_guide

Some suggestions

Open
#190 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Common Workflow Language
Stars
42
Forks
65
PR merge metrics
No merged PRs in 30d

Description

Here are a few things I found confusing as I went through the user guide:

- On this page: https://www.commonwl.org/user_guide/07-containers/index.html
it's confusing that the hello.js file is made on the command line, while other files are copy+paste. I think this shows up on other pages as well. I was wondering where the `hello.js` file came from since all the other files I made manually. I think it would be easier for the user to follow if this was consistent.

- the same page says "`baseCommand: node` tells CWL that we will be running this command in a container". This confused me. Is "node" some kind of special command? Does that mean you can't have a native command named 'node' ? How exactly does that tell CWL that we will be running this in a container? Why doesn't CWL us the DockerRequirement hint/requirement to tell if it's running in a container, and how would you run a different command in a container?

- The example tool here: (https://www.commonwl.org/user_guide/17-metadata/index.html) is running `wc -l` on a binary file (bam format), which doesn't make sense. maybe this is just a non-working example, but still, it would be nice if the examples made sense

Contributor guide

Open the contributing guide

Research direction

Start with the user guide's 07-containers page and its hello.js example, then review the 17-metadata example linked in the issue. Make file-creation instructions consistent, clarify how baseCommand relates to containers and DockerRequirement, and ensure the bam example is meaningful or replaced.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, javascript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.