Review the amount of "should" in the docs

[michaelwood]

In NVC (non-violent communications) practice the word "should" is usually avoided to reduce the likelihood of the divisive "good/bad" pattern based on value judgements from the author(s) as this may be heard by people receiving the communication.

I suggest we review them and replacing where possible, couple of examples:

-Documentation should:
+Documentation aims:

-- Reflect practice not theory, and should be updated if the two start to diverge.
+- Reflect practice not theory, to be updated if the two start to diverge.

-The decision portfolio manager should:
+The decision portfolio manager is responsible for:

-- New decisions should be introduced via a structured agenda item when they first appear, to allow for early feedback.
+- New decisions can be introduced via a structured agenda item when they first appear, to allow for early feedback.

There are 26 more instances (git grep -i "should" | wc -l).

[robredpath]

I've tried to use this documentation as part of getting the OA/OR stuff moving and I've found it hard to know what to do where there appears to be a choice "you can do..." but no guidance around how to make that choice.

So, I would prefer more imperatives ("this is what to do") and fewer choices.

To that end:

-- Reflect practice not theory, and should be updated if the two start to diverge.
+- Reflect practice not theory, to be updated if the two start to diverge.

^^ is better - it tells me what needs to happen

-- New decisions should be introduced via a structured [...]
+- New decisions can be introduced via a structured [...]

^^ is worse - how do I decide whether a structured agenda item is the right thing to do?

[duncandewhurst]

+1 to @robredpath's observation: 'should' and 'can' carry different meanings.

I'm not too familiar with NVC, but the above does make me question whether it is applicable to normative documentation?

If the word 'should' is a particular issue, then https://datatracker.ietf.org/doc/html/draft-hansen-nonkeywords-non2119-04 offers some alternatives with the same meaning: ought to, encouraged, suggested.

[michaelwood]

Yeah, ignore my "can" suggestion, agree that doesn't work. I think it would improved with an active voice (as in this kind of active voice), doing so also makes the sentences "NVC".

e.g.

- New decisions should be introduced via a structured [...]
+ Introduce new decisions via a structured [...]

[duncandewhurst]

+1 to use of active voice and to Google's technical writing resources :-)

[robredpath]

+1 , I like that and it's clear what to do