Compose: Document only one version of the YAML file

[etoews]

The Compose File Reference documents both version 1 and 2 of the file format simultaneously. This makes for a very confusing read.

Only the current version should be documented at Compose File Reference. Previous versions should be handled like other Docker docs (e.g. Docker 1.9).

If the intention behind having both version 1 and 2 in the same doc is to help people upgrade their files, I think that use case would be much better served by a dedicated migration guide.

Keep up the good work all. It's great to see Compose progressing!

[dnephin]

We have a migration guide: https://docs.docker.com/compose/compose-file/#upgrading

We include both versions because both versions are supported by the current version of Compose, 1.6. If we drop support for the V1 config, we would remove it from the docs.

Was there a specific section that you found confusing? I believe we've identified when a particular section is not available in one of the versions.

[etoews]

Text like "Version 1 file format only. In version 2, use logging." and "Version 2 file format only. In version 1, use net." is pervasive throughout the doc. As I'm reading through it, I'm _constantly_ have to do a little if/then in my head to see if it applies to me. It's a cognitive drain and contributes to a feeling of confusion.

[aanand]

Yep, that's definitely a drawback of the current approach. However, if we document the two formats separately, it'll lead to confusion when people don't realise which version of the file they're reading the docs for, or that there even _are_ multiple versions. So it's a trade-off.

I'd be interested to know what you're currently reading the reference for. "As I'm reading through it" makes it sound like you're reading over the whole thing to learn what options are available to you, whereas I think we're really optimising for people who are looking up the reference for a specific option.

[etoews]

Yep, that's definitely a drawback of the current approach. However, if we document the two formats separately, it'll lead to confusion when people don't realise which version of the file they're reading the docs for, or that there even are multiple versions. So it's a trade-off.

You could make the same argument about the Docker Engine CLI but they document previous versions separately ala https://docs.docker.com/v1.9/engine/reference/commandline/cli/

A lot of other projects have ways of reducing the confusion for what version you're reading like https://docs.djangoproject.com/en/1.8/ or http://doc-conversion.readthedocs.org/en/v1.1.1/

I'd be interested to know what you're currently reading the reference for. "As I'm reading through it" makes it sound like you're reading over the whole thing to learn what options are available to you, whereas I think we're really optimising for people who are looking up the reference for a specific option.

I started out wanting to learn how volumes and volumes_from in version 2 worked with Swarm. That led me to opening #3077. As I was scrolling through the ref, trying to pick up all of the details I needed, I found myself distracted and confused by the version 1/2 stuff.

[sfsmithcha]

What if we moved the versioning concerns earlier in the doc, so that the reader knows early on how to figure out the versioning issues before using the reference? Then make it clear the current doc includes the current version (v2) and link to a separate article for (v1) reference.

I think having multiple versions combined in a single doc is easier when the changes tend to be fairly simply additive/reductive. But in this doc some of the rules are different:

Note: In the version 1 file format, build is different in two ways:

Only the string form (build: .) is allowed - not the object form.
Using build together with image is not allowed. Attempting to do so results in an error.

[etoews]

:+1:

If you could get it down to a single area with "If you're working with version 1, do this. If you're working with version 2, do that. If I'm migrating, look over there." that would be a big improvement.

[aanand]

@moxiegirl @londoncalling Thoughts on this?

[londoncalling]

@aanand I'll have a look at the file today, and see if it makes sense to take this approach

[londoncalling]

@aanand @everett-toews @moxiegirl @sfsmithcha @shin- (looping in Joffrey)

I looked again at the Compose File Reference, and I think that trying to isolate all information about each version to a single section will not be as effective as the current approach.

The current approach provides _both_:

• a Versioning topic that captures differences between the two versions, gives global examples, and explains how to upgrade from v.1 to v.2
• detailed notes at every build option that is affected by versioning differences, along with examples for that option, and links to the Versioning topic

This way, all workflows are served.

• If someone is in the middle of writing a Compose file and links to the top of this page, they'll see a note on "Versioning" with a link to that topic.
• If they link into the file at a particular build option (like dockerfile or links) they will also see the detail they need to define those options properly in either version, _and_ get links back into the "Versioning" topic to read more about it.

If you just have a single topic, without notes and links at every build option, users might easily miss the versioning information and how it applies to a particular option. If you just give them the links, and not the detail right there at the definition for each build option, then they are going to have to link back and forth or keep multiple pages open to refer to while they are working on their Compose file.

Granted, that if you just read through this file, there's a lot to take in with the embedded information about each version. But if you are actually _using_ the document to format a Compose file, it's a more pragmatic, useful reference. I think this latter case takes higher priority.

I referred to this file when I was working through the 3 Compose sample apps (Django, Rails, and Wordpress), and found it to be a pretty quick and effective reference for what's admittedly a challenging docs problem.

[etoews]

I did use the document to format a Compose file. It wasn't just idle reading. That's what prompted me to file the issue. I was writing a version 2 file and kept tripping over all of the version 1 stuff.

It's the "all workflows are served" bit that doesn't work for me. Personally I think users would be better served by separate documents designed for a particular task (e.g. I'm writing a version 1 file, I'm writing a version 2 file, I'm migrating from version 1 to 2).

I think we disagree on that point and of course that's okay. You reviewed the issue and gave it serious consideration. I appreciate that. Cheers.

[londoncalling]

@everett-toews Thanks for your feedback, and making the effort to write this. I'll definitely look at it again when I have a little more time next week to see if I can figure out a way to address the issues you had with the way this is formatted now. I just couldn't quickly see a good docs solution, but I will give it more attention to see if I can come up with something a little better. --Thanks again!

[etoews]

It looks like this has been solved.

• https://docs.docker.com/compose/compose-file/compose-versioning/
• https://docs.docker.com/compose/compose-file/
• https://docs.docker.com/compose/compose-file/compose-file-v2/
• https://docs.docker.com/compose/compose-file/compose-file-v1/

Thanks!

[londoncalling]

@everett-toews please let me know if the new re-org works for you, and if you have further comments to make it better. I _think_ I addressed my own and Aanand's concerns about splitting these files out re: confusion among the versions, etc. Let me know what you think.