Avoid weasel words/justification filler phrases

[MatheusRich]

No description provided.

[vburzynski]

suggestion: What you you think about inverting the framing to present the guideline in a positive lens?

I feel like your third bullet point is the core concept here, the meat of what the guideline is getting at. What would you think of surfacing that as the primary idea?

Perhaps something along the lines of:

Suggested change

	- **Avoid [weasel words]/[justification filler phrases]**
	- "Researchers say that", "it's a best practice".
	- Be clear and explain the tradeoffs and impacts of a particular solution.
	- **Strive for clarity and articulate your reasoning.**
	- explain the forces, considerations, trade-offs and/or impacts behind your feedback or suggested solution.
	- It's helpful to avoid [weasel words]/[justification filler phrases] — "Researchers say that", "it's a best practice".

I'd argue that avoiding filler phrases and weasel words alone won't increase the information communicated. It would remove the impression of communicated information that can lead to ambiguity. The removal would need to be coupled with added explanation/articulation of one's reasoning. Similarly, feedback that fully explained one's reasoning, yet happened to include some weasel words or filler — while being a bit verbose and having room for improvement — would fully communicate one's reasoning.

Some reasons to consider a positive framing over negative framing because:

• a positive frame tends to surface the concept or theory behind the guideline
• a positive orientation emphasizes things that can be added (an opportunity for growth or what can be gained)
• a negative frame emphasizes the fault or lack of something
• when pointing out what not to do, it can be easy to forget to mention what to do instead (Though you do provide an alternative and preferred approach).
• too many rules of "what not to do" can start to feel restrictive/legalistic/pedantic/puritanical/bureaucratic (not sure I'm finding the right word)

ref - https://notes.andymatuschak.org/z63PA5ATVi8oyhyLgeGvL3p
ref - https://www.nicolecw.com/marketing/copywriting-positive-framing-negative-framing/

[MatheusRich]

I'm torn about that. While I like the positive framing, I fear it becomes too generic (too similar with the first bullet point in this file).

I'll let others chime in and leave their thoughts. If folks prefer the positive version, I'll update it. Thank you!

[vburzynski]

If it's similarity to other guidelines, is there an opportunity for a larger refactoring? (I can't quite think of what that might look like though).