Consider using grammarly or hemingway to make language more understandable/inclusive

[jina]

Comment: #52 (review)

[kevinmpowell]

I'm going to start running the spec through hemingwayapp.com one section at a time.

[kaelig]

Cross posting my comment in the PR above (#76 (comment)) here – note that I'm a frequent user of both Hemingway and Grammarly, and encourage editors to use them.

---

I agree with the intent, but think an over-reliance on Hemingway is detrimental to the readability and clarity of this doc.

I find that following Hemingway's suggestions too closely leads to a succession of tiny sentences that can read as quite dry, and breaks the flow of otherwise very readable content. In one of the sentences, all jargon was removed in an undesirable lossy rewrite.

My guidance is to use Hemingway sparingly, and take its suggestions for what they are: suggestions.

👍🏻 It's useful to avoid very long sentences, repetitions, and spot passive voice that would read better as active.

👎🏻 It warns about jargon that's actually important in our context: technical reports are aimed at experts who rely on this vocabulary to derive precise meaning.

---

(Grammarly allows to specify the target audience, tone, level of formality… I personally find it better than Hemingway for professional writing like technical proposals, and still use Hemingway for blog posts)

[jina]

That's fair. I wasn't necessarily saying we needed to use Hemingway. The purpose was to simplify the language a little bit, and I know those tools have helped me, so it was just a suggestion to consider a tool. I'm fine if we want to use just Grammarly!

[christianmartinnies]

My five cents: We are trying to collaborate in between various disciplines here and from my personal experience i recommend, trying to be as precise as possible. I think, once we implemented a common language it will be beneficial—how to reach that is a different story on it's own.
So this is rather a matter of glossary but i would love to see maximum of inclusiveness as possible over here (heart)

[ChucKN0risK]

Decision

We’ll pay attention to write the spec in a way that it remains understandable and clear for everyone.

We’re closing this issue for now, but may reopen it in the future if needed.