Clarify volumes docs.

[buchanae]

64 and #79 both comment on understandable confusion around the volumes field. This attempts to add more docs around it, but maybe it's still not enough. This is a confusing feature that seems to arise from needing to stitch together multiple container filesystems.

Would love feedback from @mbookman and @erikvdbergh on this one.

[mbookman]

Thank-you, Alex. The comment added makes the usage clear to me.

There is something about the name volumes and the actual usage that seems unexpected, though it is hard to put my finger on it. I think with "volume" I am expecting either specification of a disk (with size and disk type) or specification of both ends of the -v (host and docker paths).

Thinking of some other naming suggestions, disk_paths or directories might be a bit simpler. That the description you have added of a volumes is that they are directories points me to that being a better name. Would there be any confusion if they were simply called directories?

[pditommaso]

👍

[buchanae]

@mbookman Ya, the term volumes is overloaded. We'll try to come up with something more straightforward. Thanks for the suggestions.

Other ideas:

• shared_directories
• common_directories
• common_data

Also, we could define one single path that implementations should share. Also, there's still the discussion of #59 which would affect this.

[buchanae]

Sorry, I think this was merged at the wrong time. Luckily it's just documentation. I've created an issue for renaming volumes in #100