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:

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

Left-side menu:

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

FAQs

Why isn't my documentation showing up?