Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Stylistic issues in the spec #151

Open
zugz opened this issue Sep 1, 2018 · 0 comments
Open

Stylistic issues in the spec #151

zugz opened this issue Sep 1, 2018 · 0 comments

Comments

@zugz
Copy link
Contributor

zugz commented Sep 1, 2018

This is just to record some general stylistic issues in the spec which bug me.
This list is undoubtedly incomplete.

  • The pronoun for a peer is sometimes "him". Remind me which century this is?

  • More often, it's "them", which isn't too bad, except that "themselves" is
    often used for a single peer, which is confusing. I would either use "it"
    for the peer, or use "themself".

  • Tense and modality are used inconsistently - sometimes an implementation
    "will" do something, often it "does" it, and occasionally it "should" or
    "must" do it. We should decide whether this is describing the behaviour of
    current implementations, in which case present tense "does" seems best to
    me, or whether it is defining a conforming implementation, in which case use
    of "may", "should", and "must" as in RFCs would be appropriate.

  • There should be a typographical convention for introducing a definition. I
    favour bold text, as in "A gostak is a distimmer of doshes".

  • "group", "groupchat" and "group chat" are used interchangeably; we should
    replace them all with "conference".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant