Have you ever found yourself (desperately?) searching for WDL (Workflow Description Language) documentation that suits your needs and coming up short? I have. I was in that boat a year ago when I joined the Broad. I had never heard of WDL before, but I was starting to document WDL scripts for the Pipeline Development team, so I needed to learn quickly. In my search, I found several resources that I would later realize are quite helpful. But at that time I was looking for something really basic to get me started and what I was finding felt a bit too advanced. My team, User Education, created some great basic resources a number of years ago, but unfortunately, they had become out of date.
I remember being really frustrated; the only resources that seemed geared toward beginners weren’t usable because they hadn’t been updated in years. And I’m not the only person who felt this way. In July 2022, a survey of workflow users in Terra revealed that more than 75% were very interested or somewhat interested in learning more about coding in WDL and 50% have used or wanted to use those introductory materials to learn WDL, but weren’t able to because the documentation was outdated. Users also told us they wanted to see more tutorials and example workflows. Without these resources, they were left with limited options for learning WDL.
It’s because of that user feedback and my own experience that I’m especially excited to announce that my team recently finished a total overhaul of the introductory WDL materials. The updated resources include:
- A new wdl-docs GitHub repository with a section dedicated to resources created by the WDL community.
- A new wdl-docs website to host the documentation from the new wdl-docs GitHub repository.
- Updates to all existing WDL syntax documentation to match the WDL 1.0 spec. You can now find the docs on the new wdl-docs GitHub repository.
- 17 new articles, 11 cookbook-style docs to teach users about specific use-cases and provide example workflows and 6 best practices docs to help users understand some of the grayer areas of coding in WDL, like what to consider when trying to optimize costs. Thanks to the Pipelines Development team for help developing these resources.
We hope this documentation will be useful to both new and more experienced WDL users, but also that the WDL community will help us continue to improve the documentation. The wdl-docs repository and website work best with community contributions! If you have a fix you’d like to make, a new doc you’d like to contribute or suggest, or a resource you’d like to highlight, please do so! You can check out the Home page of the wdl-docs website or the contributing guide to read about the contribution process.
Additional Resources
If you want to get started using WDL on Terra, check out our Intro to workflows on Terra Leanpub course or our T101 – Workflows Quickstart Guide and the accompanying workspace.
You can also check out the recording, materials, and the WDL-puzzles workspace from a previous WDL workshop where participants learned how to write a basic WDL workflow, bring the workflow into a Terra workspace, and run the workflow in Terra.
