Contribution Guidelines

Cromwell is an open-source project and we heartily welcome community contributions to both our code and our documentation. Here are some guidelines for adding documentation and recommendations on where we could use help the most.

First off, here are useful links:

"needs docs"

There are plenty of areas of the Cromwell documentation that need to be updated, improved, or added. Within the Cromwell repo on Github there are many issues labeled as "needs docs", so feel free to start there.

If you would like to request additional documentation, you can create a Github issue in the Cromwell repo.

Writing Tips

  1. Keep it clear, accurate, and concise.
  2. Put the most important information first.
  3. Use the second person, use “you” instead of “the user”.
  4. No passive verbs (everything is done by something).
  5. Link to the original source, don't repeat documentation.

Formatting

The documentation is written in Markdown. Click here for a Github Guide on Markdown, and click here for more tips from MkDocs.

Styling

Links:

  • Absolute: [link text](www.destinationURL.com)
    Example: [Broad Institute](www.broadinstitute.org) produces this link Broad Institute.
  • Relative: [link text](Destination_Page), where Destination_Page is the file name without the .md extension
    Example: [How to use the Cromwell CLI](CommandLine) produces this link How to use the Cromwell CLI.
  • Anchor link: [anchor text](../Path/To/Page#Anchor)
    Example: [HPC filesystems](backends/HPC#filesystems) produces this link HPC filesystems.

Code:

  • To style a word of code, use a backtick (`) before and after the word.
    Example: `file.json` produces file.json.
  • To style a block of code, use three backticks (```) before and after the block of code.
    Example:
    ```
    workflow myWorkflow {
    call myTask
    }
    ```
    produces this block
    workflow myWorkflow {  
    call myTask  
    }  
  • To use syntax highlighting, include the language after the first three backticks (```).
    Example:
    ```json
    {
    "MyWorkflow.MyTask.VariableTwo": "Variable2"
    }
    ```
    produces this block
    {
        "MyWorkflow.MyTask.VariableTwo": "Variable2"
    }

Images

  • Relative: ![](ImgName.png)
    • Example: ![](jamie_the_cromwell_pig.png) produces this image
  • Absolute: ![](URLofImg.png)
    • Example: ![](https://www.broadinstitute.org/sites/all/themes/custom/at_broad/logo.png) produces this image

REST API & Menu

REST API:

  1. Edit the cromwell.yaml to make any changes to the REST API content.
  2. Regenerate the REST API markdown file by running sbt generateRestApiDocs from the main Cromwell directory.
  3. Commit both the changes to the cromwell.yaml and the (re)generated RESTAPI.md.
  4. Once your branch is merged to the develop branch, you will see your changes on the REST API page.

Left-side menu:

To add or remove items from the menu, edit mkdocs.yml in Cromwell.

FAQs

Why isn't my documentation showing up?

How do I add to the REST API documentation?

  • Don't forget to regenerate
    After you edit the cromwell.yaml, run sbt generateRestApiDocs and commit all changes.
    Hint: Once you have regenerated the docs correctly, the hidden timestamp at the top of the RESTAPI.md file will show the current time.