the zen of workflows

[daler]

Analogous to the Zen of Python, I thought it might be useful to have some guiding principles to make it easier to make design decisions.

System-agnostic

It should be just as easy to run it on biowulf as on a mac. Should be able to bootstrap an entire working environment, including references and software.

Parameters should be easy to find

When it's time to write the methods, it should be straightforward to find the software versions and parameters used.

Complexity should live in one, and only one, place

Workflows should be as clean as possible. Any needed complexity should ideally live in one place -- in a script or a wrapper, not in a rule. This should also make writing documentation and discoverability easier.

Sane defaults -- but customization is not a second-class citizen

Workflows should be a "recommended" way, not "enforced" way, of doing things.

Documentation

Each wrapper should have a README.md; each script should either have a module-level docstring or a README.md. The readme should document inputs and outputs, expectations, and how parameters are configured. Each workflow should have a README describing its DAG, initial inputs, and final outputs

[jfear]

What doc string style do you like: numpy, epydoc, sphinx or google

[daler]

numpy, but only because that was the first standard and I've gotten used to it. I can be convinced otherwise though.

[jfear]

I like numpy too, clean and organized.