Develop an Introductory CWL tutorial

[tobyhodges]

tl;dr: We need a tutorial/lesson aimed at teaching CWL to complete beginners. Are you interested in helping to make this happen?

Based on discussions with various people in the CWL user/developer community, and my own experience learning and implementing the language, I believe that what we need is two distinct presentations of information for non-experts:

1. material designed specifically to teach CWL to novices (I'll refer to this as a lesson from now on), and
2. documentation designed to be used as a reference for those who know enough of the vocabulary and the approach to thinking about describing tools and workflows (these people are sometimes called competent practitioners - see figure below)

(image from Carpentries Instructor Training)

To use the analogy that I gave to @mr-c earlier today: the following resources are available to Python users, catering to people at different stages of learning the language:

• for novices: http://swcarpentry.github.io/python-novice-gapminder/
• for competent practitioners: https://docs.python.org/3/library/index.html
• for experts: https://docs.python.org/3/reference/

In it's current form, the CWL User Guide falls somewhere between the first two above: not quite thorough enough on the basics, lacking advice on how to think about workflows, and with too steep a learning curve to be friendly for total beginners; not detailed/exhaustive enough for those who want to move beyond the basics.

I propose that we work together to develop a Carpentries-style lesson, aimed at teaching enough CWL and "workflow thinking" to move learners from "novice" to "competent practitioner" stage. This would take the same approach used by Software or Data Carpentry to develop material with a manageable learning curve, containing plenty of exercises, with clear and achievable learning objectives, and focusing on the concepts that novices find difficult about learning CWL. We might even consider basing (parts of) it on the existing Software Carpentry Make lesson - or we might decide to start from scratch.

Note: I am absolutely not a CWL expert. What I can offer:

1. Guidance on developing good lesson material, writing good exercises, learning objectives, etc
2. Explanation and support with developing teaching material using the Carpentries lesson template
3. The opportunity for contributors to come to EMBL in 2020 to help teach this lesson as a workshop for bioinformaticians/computational biologists who want to start using CWL to describe their analyses (This offer is probably limited to travel within Europe only, I'm afraid)

What I can't offer:

1. Loads of time to work on writing material myself
2. Expert knowledge of CWL
3. Extensive experience of using CWL

Questions that I'm asking here:

1. Do you think this is a good idea?
2. What other resources already exist out there that teach CWL?
3. What were the hardest things for you when learning CWL? (Particularly interested to hear from anyone who wasn't already a computing/workflows expert here.)
4. Would you be interested in helping develop this material?

[fpsom]

I have very limited experience with CWL (mostly dabbling around in toy workflows), but I can confidently answer #1 (Absolutely YES) and #4 (I'd love to as much as I can). For #2 my response would be the mental transition from a "script-based" model, to a descriptive/abstract one.

[pvanheus]

On 1. I think it is but using what technology? Do you expect people to hand-write CWL? Or use something like Rabix Composer?
2. I learned by reading the User Guide and the specific (and other examples of CWL). So in my experience there is not a lot out there.
3. Syntax threw me. Understanding in vs input. Also some technical details like secondary files, value from statements, and expressions vs inline javascript. I still feel I don't understand the Directory type.
4. Yep, in my limited free time.

[ksebby]

1. Yes, I think that anything that makes documentation simpler and provides tutorials and examples is a good idea.
2. I used these:

• http://www.commonwl.org/user_guide/
• https://www.commonwl.org/v1.0/
• https://www.biostars.org/t/cwl/

3. Very similar to @pvanheus . Also, where there are multiple ways to specify things (map vs. array), syntax for some requirements (can't think of specific example now) took a bit of figuring out.

4. Won't have much time to develop material but would be happy to try it out and edit.

[skanwal]

Thanks for raising this issue. I would categorise myself as somewhat in the middle on the experience axis (competent but look-up stuff ).

1. A big yes! Anything to help make learning CWL easier is/will/should be greatly appreciated.
2. I personally refer to http://www.commonwl.org/user_guide/ , CWL-biostars and gitter CWL channel to ask for help or clarifications.
3. Hmm, I think it took me a while to understand connection between inputs/outputs in the main workflow VS tool files.
4. As much as I can (depending on the work schedule and deadlines), either with writing or testing.

[denis-yuen]

1. Seems like a good idea
2. (ditto from above)
3. What things are standardized in CWL and what things are left up to implementers, what things in cwltool are guaranteed to be in other engines/what things aren't, and yeah some of the syntax from above answers
4. Realistically, I probably don't have bandwidth to write.
   I'd be happy to put some eyes on reviewing and do have the ability to assigning developers new to CWL to test though

[smoe]

Please go for it.

I am not ultimately convinced, though, that novices should need to see the CWL itself. They should rather feel comfortable to use it. So, beyond some "hello, this is me, CWL, but you don't really need to care" I see introductions on sets of readily usable CWL-implemented workflows that are available for the community to run. The tutorial could then explain these workflows. There shall be quick ones that run on a laptop. And others that need queueing systems or that run in the cloud somewhere. The message to get across would be that for every execution environment there is something to execute the CWL workflow and the user does not need to change the CWL bits at all, and the tutorial shows how it is done. So, by accepting the CWL in your life you would have all you need to run current routine workflows in what Bioinformatics Service Groups are addressing all over the world. And there are no limits to compute time either thanks to a fairly smooth transition into the cloud.

The advanced user will then adjust existing workflows.

The expert sends patches to this github project?

[tobyhodges]

Thanks everyone for the feedback so far - very useful indeed! I'll keep this discussion open for a while longer to allow others to contribute and will also lead one of the weekly CWL meetings, on 10 Sep 2019, when we will discuss the subject further.

[edit: link to receive invitation to the meeting mentioned above: https://groups.google.com/forum/#!forum/common-workflow-language-videochat-invites ]

[golharam]

1. Yes - excellent idea.

2. none. The cwl website is what I use, primarily. I just posted by first question to the google group because I can't find an answer for one of my use-cases.

3. Docs, in some places, are too technical especially the getting started section. They also address very simple basic examples. As I'm converting a workflow, I'm trying to follow the docs but also apply what I'm reading to my existing workflow. This is proving harder than I thought.

4. Yes, I would.

[tobyhodges]

@golharam thank's for your enthusiastic response. Are you able to elaborate on your answer to 3? What specifically did you find too technical in this User Guide? While converting your workflow, what stage(s) did you find particularly difficult? It's these kinds of "pain points" that I would hope to specifically address in the tutorial.

[golharam]

@tobyhodges -

1. Minor point, but on https://www.commonwl.org/user_guide/02-1st-example/index.html, cwl-runner is actually cwltool with the reference implementation. I don't have a cwl-runner at this time.
2. https://www.commonwl.org/user_guide/06-params/index.html, the section "Where are parameter references allowed?" seems to in-depth for a getting starting guide. Maybe this should be a link to a reference guide instead.
3. https://www.commonwl.org/user_guide/05-stdout/index.html, an obvious question at this point, ot me, is how to rename the output file from output.txt to something else? Presumably, I've got enough knowledge know how to do some basic things. I'm going to start exploring with my own stuff.

Maybe I can download the docs and mark them up with my notes somehow and send them back. Would that help?

[tobyhodges]

Sounds great - thank you @golharam. There's also no reason why we can't address some of these points with fixes to this UG itself - pull requests to this repository are welcome :)

[DiDeoxy]

1. Do you think this is a good idea?

I really do, I'm shocked it doesn't exist already its been several years since release. Are we not supposed to be writing CWL by hand?

2. What other resources already exist out there that teach CWL?

User guide, technical documentation, github repositories, gitter, discourse, biostars. None are a comprehensive introduction though for beginners. It's really tough to learn CWL currently.

3. What were the hardest things for you when learning CWL? (Particularly interested to hear from anyone who wasn't already a computing/workflows expert here.)

Dependent inputs in workflows.

4. Would you be interested in helping develop this material?

I could contribute questions and maybe some writing of explanations (would likely need review though)

[stain]

Sign me up! We want to work with this also in BioExcel context, in particular for developing virtual training on CWL together with EBI.