Skip to content

Commit e39692f

Browse files
struanstruan
committed
update the docs for admining an instance
Covers the new volunteers screen plus question import and basic setup commands.
1 parent 3b6251f commit e39692f

File tree

3 files changed

+114
-62
lines changed

3 files changed

+114
-62
lines changed

‎ADMIN.md

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Managing an instance
2+
3+
## Basic concepts
4+
5+
An instance can cope with multiple question sets. These are called
6+
Marking Sessions. Within a Marking Session are Sections which split the
7+
questions up into logical groups. You need at least one Section.
8+
9+
By default there are three Response Types, which are the stages of
10+
marking: First Mark, Right of Reply and Audit. A Marking Session will
11+
have a current response type.
12+
13+
You will also need at least one Question Group which is used to connect
14+
Authories with questions. QuestionGroups belong to at least one Marking
15+
Session.
16+
17+
Questions have Options which are the possible responses allowed.
18+
19+
When a user answers a question a Response is created that is linked to
20+
the Question and the Authority.
21+
22+
Users have a Marker which controls which stage they are marking. For the
23+
Right of Reply the Marker can also assign a User to an Authority which
24+
will mean they can see all responses for that Authority.
25+
26+
Finally, Users are Assigned to Sections and Authoriries for a Marking
27+
Session. This controls which questions they see when the log in and is
28+
used for the First Mark and Audit stages.
29+
30+
## Initial Setup
31+
32+
The first thing you need to do is to create a Marking Session and
33+
Sections. There is a `set_up_session` management command that will do
34+
this for you:
35+
36+
```
37+
./manage.py set_up_session --session "Session Name" --sections
38+
sections.csv
39+
```
40+
41+
`sections.csv` should contain a single column, "Title" with one section
42+
name per row and be located in `data/`.
43+
44+
You will need to create a Question Group in the django admin and
45+
associate it with the Marking Session you created.
46+
47+
Finally in the admin you will need to mark the session as active.
48+
49+
## Importing Questions
50+
51+
There is an `import_questions` management command for importing
52+
questions. It takes questions from an excel file, the format of which is
53+
documented in [DATA.md](https://github.com/mysociety/ceuk-marking/blob/main/DATA.md).
54+
55+
## Setting up Authorities
56+
57+
This almost certainly will require a custom management command. There
58+
are examples for creating UK councils and UK MPs already.
59+
60+
## Setting up Volunteers
61+
62+
The front end has a bulk upload page for volunteers. This gets data from
63+
an excel sheet, again documented in [DATA.md](https://github.com/mysociety/ceuk-marking/blob/main/DATA.md). It will create users and
64+
assignments. You can set the stage and the number of assignments per
65+
user. It will error if it cannot make assignments for all the users in
66+
the sheet or for all the Authorities in the database. You can override
67+
this and make what assignments it can by checking "Always Assign".
68+
69+
Once a volunteer has been created then you can edit their assignments
70+
by clicking edit from the volunteers list.
71+
72+
You can change the stage they are assigned to by clicking their
73+
Name/Email on the same screen.
74+
75+
Currently the only way to add a volunteer is in the django admin. You
76+
will need to add a user and the associated Marker with the correct
77+
Marking Session for them to show up on the volunteers page.
78+
79+
### Exporting marks
80+
81+
Once the process is complete the `export_marks` command will generate a
82+
set of CSV files with the final marks.
83+
84+
### Mark weighting
85+
86+
The database only holds the per question marks. All generating of final
87+
marks etc is done by the `export_marks` command.
88+
89+
The final marks use a weighted mark where the possible maximum score is
90+
based on the weighting as follows:
91+
92+
* low - 1 mark
93+
* medium - 2 marks
94+
* high - 3 marks
95+
96+
The score is then calculated thus:
97+
98+
( score / max score ) * weighted maximum
99+
100+
Some questions are negatively marked in which case no weighting is
101+
applied. Likewise for unweighted questions.
102+
103+
Sections are also weighted when calculating the final total. The section
104+
weightings are currenty hard coded into the scoring code. Section
105+
weightings are dependent on the council group. Section weightings are
106+
applied to the weighted section totals.
107+
108+
It is the weighted percentages that are displayed on the Scorecards
109+
site.

‎ARCHITECTURE.md

+2
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,11 @@ to the stats menu which provides various summary data.
3030

3131
The important models are:
3232

33+
* Marking Session - overall project
3334
* PublicAuthority - local authority details
3435
* Section - question sections
3536
* Question - Question details
37+
* QuestionGroup - connects questions with authorities
3638
* Option - Possible answers for a Question
3739
* Response - Answer for a question
3840
* Assigned - Volunteer assignments

‎README.md

+3-62
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,9 @@ questions and assign them to the relevant councils. The questions data
4848
should be downloaded as an Excel sheet from the Google sheet populated
4949
by CEUK.
5050

51-
Details on file strucures can be found in DATA.md
51+
Details on file strucures can be found in [DATA.md](https://github.com/mysociety/ceuk-marking/blob/main/DATA.md).
52+
53+
Form more details on managing an instance see [ADMIN.md](https://github.com/mysociety/ceuk-marking/blob/main/ADMIN.md).
5254

5355
### Data structure
5456

@@ -87,67 +89,6 @@ admin. An assigment has a ResponseType as well as a Section and Council.
8789
There is also a Marker object associated with a Volunteer which
8890
determines what stage they are marking (e.g. Audit)
8991

90-
### Setting up a volunteer in the django admin
91-
92-
In the django admin add a user. Then create a Marker associated with
93-
that user and assign a ResponseType.
94-
95-
For each council you want to user to mark you can then create an
96-
Assignment setting the user, section, council and response type.
97-
98-
If you create an assignment with only a user, section and response type
99-
the user will be assigned to all councils in that section.
100-
101-
The full set of steps are:
102-
103-
* Create the user
104-
* Create a Marker for the user and set the Response Type to the
105-
relevant one. You can ignore the Authority.
106-
* Create an Assignment and set the User, Section, Authority and
107-
Response Type. You can ignore the Question.
108-
109-
Once the user has been set up they can set a password by visiting the
110-
django password reset page.
111-
112-
For initial volunteer setup there is an `import_volunteers` management
113-
command. This will take a list of volunteers and assign each of them a
114-
set number of councils in the section they are assigned until the
115-
councils have run out. If there are more volunteers than assignments
116-
then some volunteers will not be assigned. The number of councils to
117-
assign is currently hard coded in the script.
118-
119-
### Exporting marks
120-
121-
Once the process is complete the `export_marks` command will generate a
122-
set of CSV files with the final marks.
123-
124-
### Mark weighting
125-
126-
The database only holds the per question marks. All generating of final
127-
marks etc is done by the `export_marks` command.
128-
129-
The final marks use a weighted mark where the possible maximum score is
130-
based on the weighting as follows:
131-
132-
* low - 1 mark
133-
* medium - 2 marks
134-
* high - 3 marks
135-
136-
The score is then calculated thus:
137-
138-
( score / max score ) * weighted maximum
139-
140-
Some questions are negatively marked in which case no weighting is
141-
applied. Likewise for unweighted questions.
142-
143-
Sections are also weighted when calculating the final total. The section
144-
weightings are currenty hard coded into the scoring code. Section
145-
weightings are dependent on the council group. Section weightings are
146-
applied to the weighted section totals.
147-
148-
It is the weighted percentages that are displayed on the Scorecards
149-
site.
150-
15192
### Running the tests
15293

15394
First start the Docker environment:

0 commit comments

Comments
 (0)