Re: [sipcore] Eric Rescorla's Discuss on draft-ietf-sipcore-sip-push-21: (with DISCUSS and COMMENT) - the COMMENT issues

[Ben Campbell <[e-mail]>]

> On Jan 7, 2019, at 8:08 AM, Eric Rescorla <[e-mail]> wrote:
> 
> In this reply I will address the COMMENT issues:
> 
> >This document is very badly in need of editorial work for readability.
> >I would urge the responsible AD to make one.
> 
> I have done quite a bit of editorial work based on WGLC/AD comments etc. I am happy to improve it even further, but someone needs to guide me what to do.
> 
> Ben?
> 

For the record, this has already undergone a number of revisions due to editorial review in the WG and during AD evaluation. I agree it’s not ideal, but I think most of it can be understood. I fear we’ve already reached the point of diminishing returns regarding to stylistic issues.

That being said, there are some areas that would still be worthwhile to improve before this goes to the RFC editor.  I think the places where Ekr pointed out readability issues mostly deal with nested conditional statements in prose. Those should generally be avoided whenever possible;. They take a lot of effort for humans to read and comprehend.

This is especially true for center-imbedded conditions, e.g. “When you receive a  FOO request, if the request contains BAR, do BAZ.”  That would be more readable constructed as  “When you receive a FOO request that contains BAR, do BAZ.”  It often helps to break more complex procedures into steps.

Long sentences with multiple commas are often clues for this sort of issue.

Thanks,

Ben.