opendataservices / decision-pipeline

Decision Pipeline

Documentation for the Decision Pipeline, hosted at https://decision-pipeline.readthedocs.io/en/latest/

Building the documentation

Build the docs locally

Assuming a unix based system:

# Make sure you have python3 venv, e.g. for Ubuntu
# If you're not sure, try creating a venv, and see if it errors
sudo apt-get install python3-venv

# Install submodules
git submodule init
git submodule update

# Create a venv
python3 -m venv .ve    

# Enter the venv, needs to be run for every new shell
source .ve/bin/activate

# Install requirements
pip install --upgrade pip setuptools
pip install -r requirements.txt

# Build the docs
cd docs
make dirhtml

Built docs are in docs/_build/dirhtml.

Viewing the docs:

cd _build/dirhtml
python -m http.server

Then go to http://localhost:8000/ in a browser.

Building on readthedocs

Initial setup:

• Select your repo at: https://readthedocs.org/dashboard/import/
• Tick: "Edit advanced project options:"
• Click "Next" button
• Documentation type: "Sphinx HtmlDir"
• Click "Finish" button
• Click "Admin" button, then "Advanced Settings" in the left hand nav
• Requirements file: requirements.txt
• Python interpreter: "CPython 3.x"
• Click "Submit" button

Translations

Translations are generally done using this transifex project. Create one at https://www.transifex.com/OpenDataServices/add/ :

• Select "Public project" and "File-based Project".
• Add the url of the project to this README, e.g. https://www.transifex.com/OpenDataServices/sphinx-base/dashboard/

How to push new text up to Transifex:

First, do a local build, then:

cd docs
make gettext
sphinx-intl update-txconfig-resources --transifex-project-name <project-name>
tx push -s

When the translations are filled in transifex you need to run:

tx pull -a -f

These should then be commited and then pushed to GitHub (so that actual deployed translations are always version controlled).

Running the build in another language:

make -e SPHINXOPTS="-D language='<language code>'" html

If translations are added locally, these can also be pushed up to Transifex:

tx push -t --skip

decision-pipeline's Issues

Non-members and decision making

"Employee" is currently defined as:

A non-member employee of the co-op does not directly participate in making decisions [...]

I think there is scope for guidance about decisions that can be actively participated in by non-members. Non-members needn't be excluded from all decisions. For example, if we were deciding the frequency and format of whole-coop meetings over the next year, this is a decision that all employees can participate in making, without it affecting Director-level responsibilities.

(Or is the Decision Pipeline strictly only for Director-level type decisions?)

Decisions need to go out for feedback and then back to previous states

Current process gives off quite a linear vibe, when feedback can be:

• necessary
• part of a multi-stage process

So, I think:

• the documentation should reflect that consultation is flexible, i.e. things go in and out of a consultation state in parallel with whatever else is happening
• the board, notification, and reviews should act as prompts for responding to consultations - and reflect that decisions are potentially blocked by lack of engagement

Review the amount of "should" in the docs

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).

Add "introducing a new issue" activity

Currently implicit when it should be explicit

Export to ODT script

Sphinx can build to a single HTML file, which can be converted to ODT using pandoc.

This results in a load of links that don't work in the doc.

Investigate a pre/post-processing script to remove these.

Decision sponsor vs decision facilitator

In our consent decision making docs we define a facilitator as

Facilitator: Someone willing to run the consent decision making process. They make sure that everyone involved has engaged with the proposal and that all reactions are understood correctly. This person is not usually the proposer.

In the "As a decision sponsor we have":

As a decision sponsor you have overall responsibility for moving a decision through the decision pipeline. [...]

To me a 'sponsor' has a vested interest in a particular outcome and I think that doesn't always need to be the case (in fact it can be an advantage not to be) and may shrink the pool of people willing to do it. So I would suggest we change sponsor to facilitator to make the terminology consistent. Alternatively we could change it in the consent decision making documentation.

Using 'mandate' and 'advice' for delegated decisions

Would it be helpful to introduce some of the language familiar from the Improvement Group decision mechanisms - "mandate" and "advice process" - with regard to "delegated" decisions?