List of user guide issues

[mr-c]

• demonstrate re-usable custom types demonstrate re-usable custom types in the user guide common-workflow-language#438
• demonstrate use of scicrunch.org to find IRIs for SoftwareRequirement demonstrate use of scicrunch.org to find IRIs for SoftwareRequirement in the user guide common-workflow-language#437
• add #!/usr/bin/env cwl-runner to user guide and examples add #!/usr/bin/env cwl-runner to User guide and its examples common-workflow-language#436
• document optional enum syntax add optional enum syntax to user guide common-workflow-language#392
• document in user guide that multiple parameter references and string concatenation are possible without InlineJavascript document in user guide that multiple parameter references and string concatenation are possible without InlineJavascript common-workflow-language#389
• Review SMC_RNA docs for inclusion with user guide Review SMC_RNA docs for inclusion with user guide common-workflow-language#388
• add (link to) reference implementation installation instructions add link to reference implementation installation instructions to user guide common-workflow-language#367
• better document the 'default' and 'valueFrom' fields on WorkflowStepInput better document the 'default' and 'valueFrom' fields on WorkflowStepInput common-workflow-language#359
• capture docker+CWL best practices from Denis Yuen et al. capture docker+CWL best practices from Denis Yuen et al. common-workflow-language#347
• Tutorial inconcistencies Tutorial inconcistencies common-workflow-language#318
• secondaryFiles secondaryFiles are undocumented common-workflow-language#270
• how to reuse custom record types document how to reuse custom record types (what to do about inputBindings?) common-workflow-language#241
• Apply the readme checklist Apply the readme checklist common-workflow-language#223
• rework Record inputs, dependent and mutually exclusive parameters rework Record inputs, dependent and mutually exclusive parameters #386
• metadata proposal Metadata proposal common-workflow-language#364

[evan-wehi]

I think even before getting into syntax details the user guide needs to give a much better conceptual description of the CWL objects and in general terms how they might be constructed and manipulated. Then the logic behind why CWL is the way is will be much clearer and will help people like me solve specific problems. For example, I hit the common issue that bam indexes need to travel along side the bam files even though the tools don't explicitly reference them. I found the solution on biostars (I think). This is it:

  #
  # Gather human bam and index into one dependency
  #
  gather:
    run:
      class: ExpressionTool

      inputs:
        bamFile:
          type: File
        bamIndex:
          type: File

      outputs:
        combined:
          type: File

      expression: >
        ${
          var ret = inputs.bamFile;
          ret["secondaryFiles"] = [
            inputs.bamIndex
          ];
          return {"combined" : ret};
        }

    in:
      bamFile:
        source: sort-human/sorted
      bamIndex:
        source: index-human/index

    out: [combined]

This does makes no sense to me. It seems to be javascript manipulating an internal CWL object. Without a model of what's going in CWL not only do I not understand this but I have no way to solve similar issues (of which there are many).

CWL is very rich, the user guide also needs much more coverage of its features. In particular, what can be done with JS needs more coverage. (Please bear in mind, some people are allergic to JS.)

[tobyhodges]

Thanks @evan-wehi this is a good point. And I agree completely about the need for more coverage of features in general.

I'm nearly done with the more functional aspects of migrating the gentle intro material, at which point I hope that we can quickly begin to add additional sections and flesh out what is there already.