Removal of Personal Pronouns From Specs

[Samyoul]

Introduction

The specifications have a mix of formal and informal language. Use of personal pronouns is generally common in informal text, and generally avoided in formal text.

It has been identified that:

• Informal language exists and should be changed
• Changes to the language would constitute a significant change to the specs
• Change should be made in a dedicated PR

Example

The other node types are optional, but we RECOMMEND you implement a Mailserver

The other node types are optional, but it is RECOMMEND to implement a Mailserver

Proposal

• [x] Decide if specifications should have a consistent tone and mode of language (Answer: Yes)
• [x] If a consistent tone is required, what the tone should be (Formal tone)
• [x] Implement the changes in language

Notes

These changes could also have a major impact on the structure of the specification documents. For example:

1-client.md#p2p-overlay-1 has the following subsections

• Why devp2p? Why not use libp2p?
• What about other RLPx subprotocols like LES, and Swarm?
• Why do you use Whisper?
• I heard you were moving away from Whisper?
• Why do you not use Discovery v5 for node discovery?
• I heard something about mailservers being trusted somehow?

These sections are more approachable and easier to read as they are written in an inviting and engaging tone. I feel that we should make a distinction between what is supplementary information that can be written in an informal manner and what is instructive or descriptive information that is better suited to formal language.

References

• https://www.uts.edu.au/current-students/support/helps/self-help-resources/grammar/formal-and-informal-language

[decanus]

I think @oskarth and I originally wanted to use no personal pronouns and this might have slipped through the cracks a bit. Happy to have this be done though.

[oskarth]

Agree, feel free to issue PRs that make the language more consistent and appropriate