Merge pull request #152 from common-workflow-language/140-ask-better-questions

Improve question wording

Author: mr-c

_episodes/02-1st-example.md

@@ -3,7 +3,7 @@ title: "First Example"
 teaching: 5
 exercises: 0
 questions:
-- "How do I wrap a simple command line tool?"
+- "How do I write a CWL description of a simple command line tool?"
 objectives:
 - "Learn the basic structure of a CWL description."
 keypoints:

_episodes/03-input.md

@@ -3,8 +3,8 @@ title: "Essential Input Parameters"
 teaching: 10
 exercises: 0
 questions:
-- "How do I describe inputs to a command?"
-- "How do I specify the order in which inputs appear in a command?"
+- "How can I pass arguments to a command?"
+- "How is the order of parameters defined for a command?"
 objectives:
 - "Learn how to describe and handle input parameters and files to a tool."
 keypoints:

_episodes/04-output.md

@@ -3,7 +3,8 @@ title: "Returning Output Files"
 teaching: 10
 exercises: 0
 questions:
-- "How do I describe outputs from a command?"
+- "Where does the output of a command go?"
+- "How can I save the output of a command?"
 objectives:
 - "Learn how to describe and handle outputs from a tool."
 keypoints:

_episodes/05-stdout.md

@@ -3,7 +3,7 @@ title: "Capturing Standard Output"
 teaching: 10
 exercises: 0
 questions:
-- "How do I capture a tool's standard output stream?"
+- "How do I capture the standard output stream of a command?"
 objectives:
 - "Learn how to capture streamed output from a tool."
 keypoints:

_episodes/06-params.md

@@ -3,7 +3,7 @@ title: "Parameter References"
 teaching: 10
 exercises: 0
 questions:
-- "How do I reference input parameters in other fields?"
+- "How can I re-use parameter values in another location?"
 objectives:
 - "Learn how to make parameter references in descriptions."
 keypoints:

_episodes/09-array-inputs.md

@@ -3,7 +3,7 @@ title: "Array Inputs"
 teaching: 10
 exercises: 0
 questions:
-- "How do I specify input parameters in arrays?"
+- "How do I provide multiple values for a single argument?"
 objectives:
 - "Learn how to provide parameter arrays as input to a tool."
 - "Learn how to control the organization of array parameters on the command
@@ -75,7 +75,6 @@ separator string.
 
 Note that the arrays of inputs are specified inside square brackets `[]` in `array-inputs-job.yml`. Arrays can also be expressed over multiple lines, where
 array values that are not defined with an associated key is marked by a leading
-`-`.
 This will be demonstrated in the next lesson
 and is discussed in more detail in the [YAML Guide](/yaml#arrays).
 You can specify arrays of arrays, arrays of records, and other complex types.

_episodes/10-array-outputs.md

@@ -3,7 +3,8 @@ title: "Array Outputs"
 teaching: 10
 exercises: 0
 questions:
-- "How do I specify tool outputs as arrays?"
+- "What do I do when a tool produces output in more than one file?"
+- "How do I specify which output files should be kept?"
 objectives:
 - "Learn how to create arrays of output files."
 keypoints:

_episodes/11-records.md

@@ -3,7 +3,7 @@ title: "Advanced Inputs"
 teaching: 10
 exercises: 0
 questions:
-- "How do I describe dependent and exclusive parameters?"
+- "How do I describe which parameters must and must not be used in combination?"
 objectives:
 - "Learn how to use records to describe the relationships between inputs."
 keypoints:

_episodes/14-runtime.md

@@ -5,7 +5,7 @@ exercises: 0
 questions:
 - "How do I create required input files from input parameters at runtime?"
 - "How do I invoke a script rather than just a simple command line?"
-- "How do I make inputs available to my script?"
+- "Besides `inputBinding`, how else can I pass arguments to the tool?"
 objectives:
 - "Learn how to create files on the fly during runtime."
 - "Learn how to use expressions in bash scripts."
@@ -15,7 +15,7 @@ created during tool runtime."
 ---
 Sometimes you need to create a file on the fly from input parameters,
 such as tools which expect to read their input configuration from a file
-rather than the command line parameters, or need a small wrapper shell script.  
+rather than the command line parameters, or need a small wrapper shell script.
 
 To generate such files we can use the `InitialWorkDirRequirement`.
 
@@ -26,7 +26,7 @@ To generate such files we can use the `InitialWorkDirRequirement`.
 ~~~
 {: .source}
 
-Any [expressions](../13-expressions/index.html) like `$(inputs.message)` are expanded by the CWL engine before creating the file; here inserting the value at the input `message`. 
+Any [expressions](../13-expressions/index.html) like `$(inputs.message)` are expanded by the CWL engine before creating the file; here inserting the value at the input `message`.
 
 > **Tip:** The _CWL expressions_ are independent of any _shell variables_ used later during command line tool invocation. That means that any genuine need for the character `$` should be **escaped** with `\`, for instance `\${PREFIX}` above is expanded to `${PREFIX}` in the generated file to be evaluated by the shell script instead of the CWL engine.
 

_episodes/15-staging.md

@@ -3,7 +3,7 @@ title: "Staging Input Files"
 teaching: 10
 exercises: 0
 questions:
-- "How do I stage input files in the working directory?"
+- "What can I do if a tool needs to be able to write output to the location where its input files are stored?"
 objectives:
 - "Learn how to handle situations where a tool expects to write output files to
 the same directory as its input files."

_episodes/16-file-formats.md

@@ -3,7 +3,8 @@ title: "File Formats"
 teaching: 10
 exercises: 0
 questions:
-- "How can I allow type-checking of input and output files?"
+- "How can I mark the required file format for input files?"
+- "How can I mark the produced file format of output files?"
 objectives:
 - "Learn how to unambiguously specify the format of `File` objects."
 keypoints:
@@ -23,7 +24,7 @@ others. You can browse existing file format listings for IANA [here][IANA] and
 for EDAM [here][EDAM].
 
 In the next tutorial, we explain  the `$namespace` and `$schema` section of the
-document in greater detail, so don't worry about these for now.  
+document in greater detail, so don't worry about these for now.
 
 Note that for added value `cwltool` can do some basic reasoning based on file
 formats and warn you if there seem to be some obvious mismatches.

_episodes/17-metadata.md

@@ -3,7 +3,7 @@ title: "Metadata and Authorship"
 teaching: 10
 exercises: 0
 questions:
-- "How do I provide information for people to cite my tool descriptions?"
+- "How do I make it easier for people to cite my tool descriptions?"
 objectives:
 - "Learn how to add authorship information and other metadata to a CWL
 description."
@@ -16,7 +16,7 @@ Implementation extensions not required for correct execution (for example,
 fields related to GUI presentation) and metadata about the tool or workflow
 itself (for example, authorship for use in citations) may be provided as
 additional fields on any object. Such extensions fields (e.g. `format: edam:format_2572`)
-can use a namespace prefix listed in the `$namespaces`section of the document 
+can use a namespace prefix listed in the `$namespaces`section of the document
 (e.g edam: http://edamontology.org/) as described in the [Schema Salad specification][schema-salad].
 Once you add the namespace prefix, you can access it anywhere in the document as shown below.
 Otherwise one must use full URLs: `format: http://edamontology.org/format_2572`.