search

aarongable / draft-acme-ari

Internet Draft for the Automated Certificate Management Environment (ACME) Renewal Information (ARI) Extension
Other
3 stars 7 forks source link

Typos/wording suggestions #28

Closed robplee closed 2 years ago

robplee commented 2 years ago

Super subjective here so feel free to dismiss any of these as simply being me declaring "Well, I'd have written it this way."

Abstract: "an ACME server may provide hints to ACME clients" -> "an ACME server may provide suggestions to ACME clients"

Introduction: "validity period and proactive smearing of load" -> "validity period and proactive distribution of load"

Getting Renewal Information: Not quite sure of exactly what should be changed where but RFC 8555 explicitly states that the results of various endpoints is a JSON object and I'm wondering if it would be an improvement to make it clear that the renewalInfo resource is sent to the requesting client as a JSON object containing the suggestedWindow JSON object and optionally including the explanationURL? I think that wording is a bit clumsy but I think it might be a good extra precision to add?

Happy to open a PR for any and all changes considered worth doing.

aarongable commented 2 years ago

Abstract: "an ACME server may provide hints to ACME clients" -> "an ACME server may provide suggestions to ACME clients"

Great, I love it

Introduction: "validity period and proactive smearing of load" -> "validity period and proactive distribution of load"

Yep, this is an improvement.

Getting Renewal Information: Not quite sure of exactly what should be changed where but RFC 8555 explicitly states that the results of various endpoints is a JSON object and I'm wondering if it would be an improvement to make it clear that the renewalInfo resource is sent to the requesting client as a JSON object containing the suggestedWindow JSON object and optionally including the explanationURL? I think that wording is a bit clumsy but I think it might be a good extra precision to add?

I personally believe that the current language which directly copies the phrasing used in RFC8555 itself when defining each individual resource is sufficiently specific -- this document is essentially written to be read as though it were dropped wholesale into the middle of RFC8555 inline. But happy to accept suggestions!

aarongable commented 2 years ago

Fixed by #29