Doc: remove non-standard use of hyphens in doc/api/tls.markdown

[svozza]

Affected core subsystem(s)

Doc, TLS

Description of change

Fixes#5672. Removes the non-idiomatic usages of the '-' character. I also tidied up some of the phrasing, grammar, typos and punctuation throughout the whole file. If I should have done this in a separate PR, I'm happy to pull them out and leave only the hyphen changes.

Also, there seems to be an inconsistent use of 'can', 'could' and 'may' throughout the document but I decided against changing that as I don't really know what the house style is.

[claudiorodriguez]

LGTM. I think it might be a good idea to clarify this on the style guide (https://github.com/nodejs/docs/blob/master/STYLE-GUIDE.md), gonna make an issue there.

[svozza]

Ah, I didn't see the style guide, very handy. I've just updated the PR to remove all occurrences of the word 'you' in light of that document.

[eljefedelrodeodeljefe]

This PR has more than just the described changes in it. Can you exclude them please? Also the use of youshould be discussed in broader scope in the docs WG.

[svozza]

Sure thing. Can I open a separate PR with the other changes? I think the document reads much better than before.

[eljefedelrodeodeljefe]

Sure, generally. Just two remarks here. Not every hyphen qualifies for removal. Those behind acronyms especially, since those seem quite consistent to the rest of the docs. If there is something wrong in general in english or style, I'd rather suggest opening an issue at nodejs/docs. Second, while I agree on the hyphens seemingly being misplaced and hence having inferior readability of the doc, you probably have to make a good case for the other changes. But please, PR is always welcome. We discuss it there.

[svozza]

Those behind acronyms especially, since those seem quite consistent to the rest of the docs.

Do you mean 'in front of'? E.g., the ALPN/NPN and SNI ones?

Aside from the personal pronoun stuff, which I will omit from the PR, I think the other changes are pretty uncontroversial, they're mainly just fixing typos and missing definite/indefinite articles.

[eljefedelrodeodeljefe]

Yes, I mean those.

Sure, they are. They are also a bit of a nit, the WG might want to have in a broader effort. Those kind of problems are all over the docs, I mean. We'll see...

[jasnell]

LGTM

[svozza]

Yes, I mean those.

Cool. I'll change back those other hyphens.

[Trott]

Nit: Can you add Fixes: https://github.com/nodejs/node/issues/5672 to the bottom of the commit message? And maybe leave a comment on that issue so that no one else tries to grab it as a good first contribution?

[svozza]

No problem, all done.

[eljefedelrodeodeljefe]

LGTM

[jasnell]

Landed in ecbb955