Adding to Pair docs

[ruchim]

No description provided.

[geoffjentry]

👍

[cjllanwarne]

Are those Left and Right capitalizations correct? I think in the output it's all lowercase?

[ruchim]

Json to Pair coercion isn't sensitive towards capitalization (there's a test case in WDL4S for it) but I didn't realize the outputs were all lowercase, that creates a slight inconsistency. We could make it required lowercase for the future but currently Pair creation accepts "Left" or "left"

[cjllanwarne]

Minor nitpick, but otherwise 👍

[sooheelee]

Given the meaning of indexing in genomics (BWA indexing, BAM indexing, VCF indexing), this section reads confusingly for me. Also, it's unclear how a researchers would want to use this feature.

It would be nice to have one line clarifying indices being discussed have two different meanings (coding and in genomics) and also another line giving an example of how a genomicist would best use this feature, e.g. to keep file indices together with the BAM/VCF file.

Here is Ruchi's example and I think it gets right to my second request.

Pair[File, File] mySample = ("/path/to/sample.bam", "/path/to/sample.bai")

[ruchim]

@sooheelee I see--alternatively, I could move the pair member access syntax directly inside of the Pair Literals section.

[vdauwera]

The "indexing" jargon overlap is kind of inevitable -- and I don't think the burden of clarifying should be on every WDL technical doc that uses the term (that way lies some amount of madness). For one, it's a term that people familiar with scripting in bioinformatics should already understand. So the problem is really only for newbs. Obviously we want to make sure we help them navigate this stuff, so I would advocate for writing a doc about terminology for researchers looking at scripting for the first time. And when we write up a description of the Pair object for the user docs proper (WDL website/forum) we can make sure to do so in a way that is unambiguous and well furnished with domain-relevant examples.