Along with avoiding idiom, I always avoided using contractions in docs. I thought they made it harder for non-English/non-western readers to understand. English is a weird language.
moreover?
At some point we (possibly me) started using inline code to refer to site settings. For example: “Enable the discourse connect site setting.” That might be the right approach, but it feels kind of developery.
It might be worth using a consistent placeholder name to refer to Discourse sites. Maybe discourse.example.com? There’s some documentation on here that’s referring to the Discourse site as sitename.com. It really threw me off.
Some general writing advice: read what you’ve written as though you’re a member of your (see how contractions are tricky) target audience. Make sure your assumptions about the audience’s prior knowledge are reasonable.
As much as I appreciate no longer having a ton of doc topics ascribed to me, using Discourse as the author of all the team’s doc topics feels a little cold.
What’s made writing fun for me again was the advice to look for ways of putting a bit of yourself into whatever you’re writing. It could be anything, your tone of voice, your hobbies, whatever… That’s kind of the opposite of what’s being recommended here.