diff options
Diffstat (limited to 'docs/customising')
| -rw-r--r-- | docs/customising/states.md | 217 | ||||
| -rw-r--r-- | docs/customising/states_informatazyrtare.md | 88 | ||||
| -rw-r--r-- | docs/customising/themes.md | 2 |
3 files changed, 306 insertions, 1 deletions
diff --git a/docs/customising/states.md b/docs/customising/states.md new file mode 100644 index 000000000..7b89ef45d --- /dev/null +++ b/docs/customising/states.md @@ -0,0 +1,217 @@ +--- +layout: page +title: States of requests +--- + +# Request states + +<p class="lead"> + A <a href="{{site.baseurl}}docs/glossary/#request" class="glossary__link">request</a> + passes through different <strong>states</strong> as it is processed. These may + vary from one jurisdiction to another. +</p> + +The request states are defined in the Alaveteli code, and we recommend you use +them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi" +class="glossary__link">FOI law</a> in your own jurisdiction). But if you do need to +customise them, you can — see +<a href="{{ site.baseurl }}docs/customising/themes/#customising-the-request-states">Customising the request states</a> for details. + +## WhatDoTheyKnow example + +Requests made on the UK's Alaveteli instance, [WhatDoTheyKnow](https://www.whatdotheyknow.com), +may be in any of the states described below. + +Note that your site doesn't need to use the same states as WhatDoTheyKnow does. For example, +Kosovo's instance uses slightly different states: see +[this comparison of their differences]({{ site.baseurl }}docs/customising/states_informatazyrtare/). + +### States + +<ul class="definitions"> + <li><a href="#waiting_response">waiting_response</a></li> + <li><a href="#waiting_classification">waiting_classification</a></li> + <li><a href="#waiting_response_overdue">waiting_response_overdue</a></li> + <li><a href="#waiting_response_very_overdue">waiting_response_very_overdue</a></li> + <li><a href="#waiting_clarification">waiting_clarification</a></li> + <li><a href="#gone_postal">gone_postal</a></li> + <li><a href="#not_held">not_held</a></li> + <li><a href="#rejected">rejected</a></li> + <li><a href="#successful">successful</a></li> + <li><a href="#partially_successful">partially_successful</a></li> + <li><a href="#internal_review">internal_review</a></li> + <li><a href="#error_message">error_message</a></li> + <li><a href="#requires_admin">requires_admin</a></li> + <li><a href="#user_withdrawn">user_withdrawn</a></li> + <li><a href="#awaiting_description">awaiting_description</a></li> +</ul> + + +<dl class="glossary"> + + <dt> + <a name="waiting_response">waiting_response</a> + </dt> + <dd> + Waiting for the public authority to reply + <ul> + <li>The default initial state</li> + <li>Can't transition here from internal_review</li> + </ul> + </dd> + + <dt> + <a name="waiting_classification">waiting_classification</a> + </dt> + <dd> + Waiting for a classification of a response + <ul> + <li>The default state after receiving a response</li> + </ul> + </dd> + + <dt> + <a name="waiting_response_overdue">waiting_response_overdue</a> + </dt> + <dd> + Waiting for a reply for too long + <ul> + <li>Automatic, if today's date is after the request date + holidays + 20 days</li> + <li>When a user updates / visits an item in this state, thank user and tell them how long they should have to wait</li> + <li>Alert user by email when something becomes overdue</li> + </ul> + </dd> + + <dt> + <a name="waiting_response_very_overdue">waiting_response_very_overdue</a> + </dt> + <dd> + Waiting for a reply for a very long time + <ul> + <li>Automatic, if today's date is after the request date + holidays + (60 days (for schools) or 40 days (everyone else))</li> + <li>When a user updates / visits something in this state, suggest they might want to complain about it; show things they might want to do</li> + <li>Alert user by email when this state happens</li> + </ul> + </dd> + + <dt> + <a name="waiting_clarification">waiting_clarification</a> + </dt> + <dd> + The public authority would like part of the request explained + <ul> + <li>Prompt user to write followup</li> + <li>if a user sends an outgoing message on a request in this state, automatically transitions to {{waiting_response}}</li> + <li>three days after this state change occurs, send reminder to user to action it (assuming user isn't banned)</li> + <li>Can't transition here from internal_review</li> + </ul> + </dd> + + <dt> + <a name="gone_postal">gone_postal</a> + </dt> + <dd> + The public authority would like to / has responded by post + <ul> + <li>If selected, remind user that in most cases authority should respond by email, and encourage followup.</li> + <li>Give most recent authority correspondence email address for user to request postal by private email.</li> + <li>Encourage user to update thread with annotation at later date.</li> + </ul> + </dd> + + <dt> + <a name="not_held">not_held</a> + </dt> + <dd> + The public authority does not have the information requested + <ul> + <li>Suggest user might want to try a different authority, or complain</li> + </ul> + </dd> + + <dt> + <a name="rejected">rejected</a> + </dt> + <dd> + The request was refused by the public authority + <ul> + <li>Show page of possible next steps</li> + </ul> + </dd> + + + <dt> + <a name="successful">successful</a> + </dt> + <dd> + All of the information requested has been received + <ul> + <li>Suggest they add annotations or make a donation</li> + </ul> + </dd> + + + <dt> + <a name="partially_successful">partially_successful</a> + </dt> + <dd> + Some of the information requested has been received + <ul> + <li>Suggest they make a donation; give ideas what to do next</li> + </ul> + </dd> + + <dt> + <a name="internal_review">internal_review</a> + </dt> + <dd> + Waiting for the public authority to complete an internal review of their handling of the request + <ul> + <li>Tell user they should expect a response within 20 days</li> + <li>When sends email to authority, adds “Internal review of” to Subject</li> + <li>Can be transitioned from the followup form</li> + </ul> + </dd> + + <dt> + <a name="error_message">error_message</a> + </dt> + <dd> + Received an error message, such as delivery failure. + <ul> + <li>Thank user for reporting, and suggest they use a form to give new email address for authority if that was the problem</li> + <li>Mark as needs admin attention</li> + </ul> + </dd> + + <dt> + <a name="requires_admin">requires_admin</a> + </dt> + <dd> + A strange reponse, required attention by the WhatDoTheyKnow team + <ul> + <li>a user is confused and doesn't know what state to set, so an admin can intervene</li> + <li>Redirect to form to ask for more information</li> + <li>Mark as needs admin attention</li> + </ul> + </dd> + + <dt> + <a name="user_withdrawn">user_withdrawn</a> + </dt> + <dd> + The requester has abandoned this request for some reason. + <ul> + <li>Prompt user to write message to tell authority</li> + </ul> + </dd> + + <dt> + <a name="awaiting_description">awaiting_description</a> + </dt> + <dd> + This state, awaiting_description, is not really a state but a flag indicating that there is no state. + </dd> + +</dl> + diff --git a/docs/customising/states_informatazyrtare.md b/docs/customising/states_informatazyrtare.md new file mode 100644 index 000000000..e94f96588 --- /dev/null +++ b/docs/customising/states_informatazyrtare.md @@ -0,0 +1,88 @@ +--- +layout: page +title: States of requests (InformataZyrtare) +--- + +# Request states: example comparison + +<p class="lead"> + This page shows differences between states used on two different + Alaveteli instances — one in Kosovo and one in the UK. This + is a practical example showing that you can customise the states that + your site uses. +</p> + +The request states are defined in the Alaveteli code, and we recommend you use +them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi" +class="glossary__link">FOI law</a> in your own jurisdiction). + +## InformataZyrtare.org (Kosovo) example + +Requests made on Kosovo's Alaveteli instance, +[InformataZyrtare](http://informatazyrtare.org), use slightly different states +from those on the UK's instance, [WhatDoTheyKnow](http://www.whatdotheyknow.com) +(WDTK). + +Generally, this arises simply because the local legislation, or the way the +groups running the sites work, are different in different places. Alavateli +facilitates this by allowing you to customise the states that are used. + +This example is to show clearly that you can use different states depending on +your local requirements, and how that might look. See [Customising the request +states]({{ site.baseurl }}docs/customising/themes/) for details on how to do this. + +### States used by InformataZyrtare but not WDTK + + * <a href="#deadline_extended">deadline_extended</a> + * <a href="#partial_rejected">partial_rejected</a> + * <a href="#wrong_response">wrong_response</a> + +### States used by WDTK but not InformataZyrtare + + * <a href="{{ site.baseurl }}docs/customising/states/#awaiting_description">awaiting_description</a> + * <a href="{{ site.baseurl }}docs/customising/states/#gone_postal">gone_postal</a> + * <a href="{{ site.baseurl }}docs/customising/states/#internal_review">internal_review</a> + * <a href="{{ site.baseurl }}docs/customising/states/#user_withdrawn">user_withdrawn</a> + * <a href="{{ site.baseurl }}docs/customising/states/#waiting_response_very_overdue">waiting_response_very_overdue</a> + +For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}docs/customising/states/) for details. + + +--- + + + +### Details of InformataZytare states + +The states which aren't represented on [WDTK's states]({{ site.baseurl }}docs/customising/states/) are described +in a little more detail here: + +<ul class="definitions"> + <li><a href="#deadline_extended">deadline_extended</a></li> + <li><a href="#partial_rejected">partial_rejected</a></li> + <li><a href="#wrong_response">wrong_response</a></li> +</ul> + +<dl class="glossary"> + <dt> + <a name="deadline_extended">deadline_extended</a> + </dt> + <dd> + The Authority has requested deadline extension. + </dd> + <dt> + <a name="partial_rejected">partial_rejected</a> + </dt> + <dd> + Only part of the request has being refused but the successful request + to an information has not been attached. + </dd> + <dt> + <a name="wrong_response">wrong_response</a> + </dt> + <dd> + The authority has replied but the response does not correspond to the request. + </dd> + +</dl> + diff --git a/docs/customising/themes.md b/docs/customising/themes.md index 154cc0dca..cc0ca3b29 100644 --- a/docs/customising/themes.md +++ b/docs/customising/themes.md @@ -137,7 +137,7 @@ locale you support. ## Customising the request states As mentioned above, if you can possibly live with the -[default Alaveteli request statuses]({{ site.baseurl }}docs/running/states/), +[default Alaveteli request statuses]({{ site.baseurl }}docs/customising/states/), it would be good to do so. Note that you can set how many days counts as "overdue" in the main site config file — see [`REPLY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#reply_late_after_days). |