Proposal: Tone down the formal language of the Compose Specification
aevesdocker opened this issue · comments
What is the problem you're trying to solve
The Compose Specification is currently serving two purposes - as a developer-focused standard for defining container-based applications, and as the foundation for user documentation. For example, Docker Compose is the reference implementation of the Compose Specification and so the Spec is used heavily within the product documentation.
There has been limited interest elsewhere in implementing the Compose Specification and it is mostly consumed through the Docker Docs site. Given this, I would like to propose toning down the formal language used in the Compose Specification to make it more user-friendly and less verbose.
Looking at other CNCF specifications, such as the Serverless Workflow Specification, less formal language is accepted practice.
Describe the solution you'd like
Where appropriate, there are some key things I'd like to change:
- Either de-capitalize 'SHOULD/MAY/MUST' etc. or remove and rephrase the sentence to make it more active and direct.
- Instead of referring to users as 'users', refer to them more directly with 'you'.
- Replace 'Compose implementation' with simply 'Compose' to help with the reading flow (but define earlier in the Spec what we mean when we say 'Compose').
I believe this will reduce the complexity of the Compose Specification, and make it easier to navigate and consume whilst also ensuring it continues to serve this dual purpose.
- Either de-capitalize 'SHOULD/MAY/MUST' etc. or remove and rephrase the sentence to make it more active and direct.
👍 on rephrasing with a more prescriptive style. i.e "Compose SHOULD warn user" to become "Compose will warn user"
- Instead of referring to users as 'users', refer to them more directly with 'you'.
No strong opinion on this
- Replace 'Compose implementation' with simply 'Compose' to help with the reading flow (but define earlier in the Spec what we mean when we say 'Compose').
👍
Generally a plus from me! Regarding the specific points:
- Either de-capitalize 'SHOULD/MAY/MUST' etc. or remove and rephrase the sentence to make it more active and direct.
Definitely a yes! Asides from the example you've given, there's a lot of other specs that don't adhere to the strict RFC wording and I think that change will definitely positively impact readability.
- Instead of referring to users as 'users', refer to them more directly with 'you'.
I'm a bit more on the fence about this one, mostly because in examples I've seen it attempted in the Spec it's usually paired with less technical/clear content, but I think it's definitely possible to use you and address the reader directly while accurately conveying technical information – for example's sake, from the serverless workflow spec you linked:
For long-running workflow-executions, you can utilize the `keepActive` workflow property which
provides more control as to when exactly to terminate workflow execution.
Overall, okay with this.
- Replace 'Compose implementation' with simply 'Compose' to help with the reading flow (but define earlier in the Spec what we mean when we say 'Compose').
+1 from me
I guess the only concern I do have relates to the kind of information presented in the spec. Wording changes in general I'm positive on, but I do think there's a type of content that belongs in the spec and a type of content that doesn't necessarily. As an example for this, from #360, paragraphs like:
Secrets provides a more secure way of getting sensitive information in to your application's services,
so you don't have to rely on using environment variables. If you’re injecting passwords and API keys
as environment variables, you risk unintentional information exposure. Environment variables are often
available to all processes, and it can be difficult to track access. They can also be printed in logs when
debugging errors without your knowledge.
are a bit of a sticking point for me specifically, because it's subjective and a bit vague and not completely correct (e.g., using secrets doesn't really prevent an application accidentally printing sensitive information in logs). These can be handled on a case-by-case basis though, and I don't think that that should prevent the rest of the changes. (just thought it worth a call-out). I am okay with these being included, as long as we have a clear delineation between the parts of the spec that are clearly and technically laying out what Compose does for a field, and the parts such as paragraphs like these which are more subjective and "hints" related to how users can/should/use fields and what best practices in general are.
(cc @EricHripko @ulyssessouza if you have thoughts on this)
Just to let you know, we plan to timebox this issue with a 2 weeks timeframe.
If you disagree with this move please let us know by adding a comment explaining your concerns 🙏
Thanks
Sounds good to me - making the spec more accessible seems like a win-win-win 🙂
No hard opinions here... Maybe because I'm the persona that would prefer strictness over readability.
My only fear is that for #1 the language would change in a way that the distinction of SHOULD/MAY/MUST would be lost or become ambiguous.
So I'm more inclined to de-capitalization and keeping the reference to the glossary.
the language would change in a way that the distinction of SHOULD/MAY/MUST would be lost or become ambiguous.
I think it would contrariwise be more prescriptive. There are many places the spec declares "a Compose implementation SHOULD warn user ..." but the Docker Compose reference implementation doesn't. If we switch to a descriptive style "Compose will warn user ..." this just demonstrates a bug in the spec/docs or Docker Compose must be fixed.
The 2 weeks timeframe is over now, as we didn't receive any objection we'll start changing the tone of the specification