aboutsummaryrefslogtreecommitdiffstats
path: root/docs/running
diff options
context:
space:
mode:
Diffstat (limited to 'docs/running')
-rw-r--r--docs/running/admin_manual.md301
-rw-r--r--docs/running/index.md28
-rw-r--r--docs/running/server.md122
-rw-r--r--docs/running/states.md217
-rw-r--r--docs/running/states_informatazyrtare.md88
5 files changed, 756 insertions, 0 deletions
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
new file mode 100644
index 000000000..bd3a44855
--- /dev/null
+++ b/docs/running/admin_manual.md
@@ -0,0 +1,301 @@
+---
+layout: page
+title: Administrator's guide
+---
+
+# Alaveteli administrator's guide
+
+<p class="lead">
+ What is it like running an Alaveteli site? This guide explains what you can expect, and the types of problem that you might encounter. It includes examples of how mySociety manages their own <a href="/docs/glossary/#foi" class="glossary">Freedom of Information</a> site, <a href="http://www.whatdotheyknow.com">whatdotheyknow.com</a>.
+</p>
+
+## What's involved?
+
+The overhead in managing a successful FOI website is quite high. Richard, a
+volunteer, wrote a [blog
+post](http://www.mysociety.org/2009/10/13/behind-whatdotheyknow/) about some of
+this in 2009.
+
+WhatDoTheyKnow usually has about 3 active volunteers at any one time managing
+the support, plus a few other less active people who help out at different
+times.
+
+Administration tasks can be split into **maintenance** and **user support**.
+The boundaries of these tasks is in fact quite blurred; the main distinction is
+that the former happen exclusively through the web admin interface, whereas the
+latter are mediated by email directly with end users (but often result in
+actions through the web admin interface).
+
+In one randomly chosen week in December 2010, the support team acted on 66
+different events, comprising 44 user **support** emails and 22 **maintenance**
+tasks.
+
+Most of the support emails require some time to investigate; some (e.g. those
+with legal implications) require quite a lot of policy discussion and debate in
+order to address them. Maintenance tasks tend to be much more straightforward
+to address, although sometimes they need expert knowledge (e.g. about mail
+server bounce messages).
+
+During that week, the tasks broke down as follows:
+
+### Regular maintenance tasks
+
+* 18 misdelivered / undelivered responses (a.k.a. the "Holding Pen")
+* 4 requests that are unclassified 21 days after response needing classification
+* 2 requests that have been marked as needing admin attention
+* 2 things marked as errors (message refused by server - spam, full mailbox, etc) to fix
+
+### User interaction tasks
+
+* 16 general, daily admin: i.e. things that resulted in admin actions on the
+ site (bounces, misdelivered responses, etc)
+* 14 items wrongly addressed (i.e. to the support team rather than an authority)
+* 6 users needed support using the website (problems finding authorities, or authorities having problems following up)
+* 4 users wanted advice about FOI or data protection
+* 3 requests to redact personal information
+* 2 requests to redact defamatory information
+
+## Types of user interaction
+
+There follows a breakdown of the most common kinds of user interaction. It's
+intended for use as a guide to the kind of policies and training that a support
+team might need to develop.
+
+### Dealing with email that's not getting through to the authority
+
+Emails may not get through to the authority in the first place for a few
+reasons:
+
+* The recipient's domain has marked the email as spam and not sent it on
+* It's gone into the recipient's spam folder due to their own mail client setup
+* The recipient has a mail filter configured in their client that otherwise skips their inbox
+
+The first reason is the most common. The solution is to send a standard email
+to the recipient's IT department to whitelist email from your service (and of
+course send a message to the original recipient about this). The Alaveteli
+admin interface also has an option to "resend" any particular message.
+
+An Alaveteli administrator will typically only become aware of this when a
+request has become very overdue without any correspondence at all from the
+authority. Sometimes the authority's mail server will bounce the email, in
+which case it appears in the administrative interface as "needs admin
+attention".
+
+### Requests to take down information
+
+#### Legal action
+
+This is where someone tells us that information on the site might be subject to
+legal action. The scenario will vary wildly across different legal
+jurisdictions. In the UK, this kind of request is most likely to be related to
+defamation.
+
+##### Action
+
+* Get the notification by email to a central support email address, so there is
+ a written record
+* Act according to standard legal advice (e.g. you may need to temporarily take
+ down requests while you debate it, even if you think they should stay up; or
+ you may be able to redact them temporarily rather than take them down)
+* Centrally log the entire conversation and the actions you have taken
+* Get further legal advice where necessary. For example, you may get a risk
+ assessment that suggests you can republish the request, or show it with
+ limited redactions.
+
+#### Copyright / Commercial
+
+Public authorities who have not quite understood that their responses are
+public sometimes don't like this, and claim copyright. Occasionally other
+copyright assertions are made about content, but this is the most common one.
+"Commercially sensitive" data might also be considered private information.
+
+##### Action
+
+* In the case of threatened legal action, see above.
+* Otherwise, in the first instance, treat this as an advocacy case, on the
+ basis that FOI requests can be made repeatedly by anyone, the data should be
+ public anyway, and publishing it should actually save the authority money.
+
+##### Example email to authority
+
+> As I'm sure you know, our Freedom of Information law is "applicant blind",
+> so anyone in the world can request the same document and get a copy of it.
+> To save tax payers' money by preventing duplicate requests, and for good
+> public relations, we'd advise you not to ask us to take down the
+> information or to apply for a license. I would also note that
+> &lt;authority_name&gt; has allowed re-use of FOI responses through our
+> website since last year, without any trouble.
+
+
+#### Personal data
+
+This includes everything from inadvertently revealed personal data such as
+personally identifying information about benefits claimants to the name of a
+user of the site who later develops "Google remorse".
+
+##### Action
+
+* Assess request, with reference to local Data Protection laws. Don't
+ automatically presume in favour of taking something down, but weighing the
+ nuisance/harm caused to the individual which would be relieved by taking the
+ material down against the public interest in publishing / continuing to
+ publish the material. "Sensitive" personal data will typically require a
+ much higher level of public interest.
+* [WhatDoTheyKnow considers](http://www.whatdotheyknow.com/help/privacy#takedown) there to be a
+ strong public interest in retaining the names of officers or servants of
+ public authorities
+* For users who want their name removed entirely from the site, in the first
+ instance, try to persuade them not to do so:
+* Find out why they want their name removing
+* Explain that the site is a permanent archive, and it's hard to remove things
+ from the Internet once posted
+* Find examples of valuable requests they've made, to show why we want to keep
+ it
+* Explain technical difficulties of removal (if relevant)
+* With persistent requests, consider changing their account name to abbreviate
+ their first name to an initial, as this won't confuse existing requests too
+ much. Where there are grounds of personal safety, name should be removed and
+ replaced with suitable redaction text.
+* Where redaction is hard (e.g. removing a scanned signature from a PDF, ask
+ them to resend their response with redaction in place. This has a benefit of
+ training them not to do this in the future, which is a good thing.
+* Where redactions take place, it is advisable to add an annotation to the
+ request
+
+
+### Incorrectly addressed
+
+Emails that arrive at the support team address, but shouldn't have. Two main types:
+
+* Users who think the site is a place to contact agencies directly (e.g. people
+ going though immigration and asylum processes who want to contact the UK
+ Borders Agency)
+* Users who email the support email address rather than using the online form;
+ usually because they've replied to a system email rather than followed the
+ link in the message
+
+#### Action
+
+Respond to user and point them in the right direction.
+
+##### Example message:
+
+> I like to know some information about my EEA2 application which i applied on
+> july 2010.i do not get any response yet ...please let me know what i will do.
+
+##### Example response:
+
+> You have written to the team responsible for the WhatDoTheyKnow.com website;
+> we only run that website and are not part of the UK Government.
+>
+> As you are asking about your own personal circumstances you need to contact
+> the UKBA directly; their contact information is available at:
+>
+> http://www.bia.homeoffice.gov.uk/contact/contactspage/
+> http://www.ukba.homeoffice.gov.uk/contact/contactspage/contactcentres/
+>
+> You might also want to consider contacting your local MP. You could ask your
+> local council or the Citizens Advice Bureau if there is an immigration advice
+> centre where you are.
+
+##### Example message:
+
+> is the greenwaste collection paying for its self? .i suspect due to
+> the low numbers of residents taking up the scheme, what is the true
+> cost of these collections? is the scheme liable to be scrapped ?
+
+##### Example response:
+
+> You've written to the team responsible for the website WhatDoTheyKnow.com
+> and not &lt;authority_name&gt;
+>
+> If you want to make a freedom of information request to them you can do so,
+> in public, via our site. To get started click "make a new freedom of
+> information request" at:
+>
+> http://www.whatdotheyknow.com/body/&lt;authority_name&gt;
+
+### Wants advice
+
+Two common examples are:
+
+* A user isn't sure where to direct their request
+* Wants to know the best way to ask an authority for all the personal data they
+ hold about themselves
+
+##### Example request:
+
+> I would like to know at this stage under the freedom act can ask
+> directly to UK embassies or high commission abroad to disclose some
+> information. or I have to contact FCO through this website.
+
+##### Example response:
+
+> I would suggest making your request to the FCO as they are they body
+> technically subject to the Freedom of Information Act.
+>
+> When you make your request it will be sent to the FCO's central FOI team they
+> will then co-ordinate the response with the relevant parts of their
+> organisation.
+
+
+### General assistance required
+
+Can be for many reasons, e.g.
+
+* They had withdrawn their request, and an authority had subsequently
+ replied, marking the request as open again.
+* Suggested corrections to authority names / details from users or authorities
+ themselves
+* A reply has been automatically filed under the wrong request
+
+## Vexatious users
+
+Some users persistently misuse the website. An alaveteli site should have a
+policy on banning users, for example giving them a first warning, informing
+them about moderation policy, etc.
+
+## Mail import errors
+
+These are currently occurring at a rate of about two a month. Sometimes the
+root cause seems to be blocking in the database when two mails are received for
+the same request at about the same time, sometimes it just seems to be IO
+timeout if the server is busy. When a mail import error occurs, the mail
+handler (Exim) is sent an exit code of 75 and so should try to deliver the mail
+again. A mail is sent to the support address for the site, indicating that an
+error occurred, with the error and the incoming mail as attachments. Usually
+Exim will redeliver the mail to the application. On the rare occasion it
+doesn't, you can import it manually, by putting the raw mail (as attached to
+the error sent to the site support address) in a file without the first "From"
+line, and piping the contents of that file into the mail handling script. e.g.
+```cat missing_mail.txt | script/mailin```
+
+## Censor rules
+
+Censor rules can be attached to a request or to a user and define bits of text
+to be removed (either from the request (and all associated files e.g. incoming
+message attachments) or from all requests associated with a user), and some
+replacement text. In binary files, the replacement text will always be a series
+of 'x' characters identical in length to the text replaced, in order to
+preserve file length. The attachment censoring does not work consistently, as
+it is difficult to write rules that will match the exact contents of the
+underlying file, so always check the results. Make sure to also add censor
+rules for the real text and check the "View as HTML" option; this is currently
+(Sept 2013) generated from the uncensored PDF or other binary file.
+
+You can make a censor rule apply as a [regular
+expression](http://en.wikipedia.org/wiki/Regular_expression) by checking the
+"Is it regexp replacement?" checkbox in the admin interface for censor rules.
+Otherwise it will literally just replace any occurrences of the text entered.
+Like regular text-based censor rules, regular expression based rules will be
+run over binary files related to the request too, so a regular expression that
+is quite loose in what it matches may have unexpected consequences if it also
+matches the underlying sequence of characters in a binary file. Also, complex
+or loose regular expressions can be very expensive to run (in some cases
+hanging the application altogether), so please:
+
+* Restrict your use of them to cases that can't otherwise be easily covered.
+* Keep them as simple and specific as possible.
+
+
+
diff --git a/docs/running/index.md b/docs/running/index.md
new file mode 100644
index 000000000..3db94f713
--- /dev/null
+++ b/docs/running/index.md
@@ -0,0 +1,28 @@
+---
+layout: page
+title: Running
+---
+
+# Running Alaveteli
+
+
+<p class="lead">
+ Keeping your Alaveteli site up and running requires some ongoing effort.
+</p>
+
+Alaveteli is not just software. To run a successful
+<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary">Freedom of Information</a>
+site, you need to make sure day-to-day tasks get done too. Most Alaveteli sites
+are run by a team who allocate some time every day to user support and generally keeping
+the project up to date.
+
+* the [administrator's guide]({{ site.baseurl }}docs/running/admin_manual) describes
+ what you need to do and know to run your site
+
+* we've prepared a checklist of
+ [things to consider]({{ site.baseurl }}docs/running/server)
+ when setting up your production server
+
+* see the [different states a request can be in]({{ site.baseurl }}docs/running/states)
+
+
diff --git a/docs/running/server.md b/docs/running/server.md
new file mode 100644
index 000000000..63ec1800f
--- /dev/null
+++ b/docs/running/server.md
@@ -0,0 +1,122 @@
+---
+layout: page
+title: Production server best practices
+---
+
+# Production server best practices
+
+<p class="lead">
+ These notes serve as a checklist of things to consider when you're ready
+ to deploy your Alaveteli site to production.
+</p>
+
+
+## Hosting options
+
+Your production server must be reliable and secure. If you don't run your own
+servers already, consider one of these options:
+
+* Cloud Server
+* Virtual Private Server
+
+In some cases, we can host new Alaveteli projects &mdash; if you need help,
+ask us about hosting.
+
+## Cron jobs
+
+Don't forget to set up the cron jobs as outlined in the
+[installation instructions]({{ site.baseurl }}docs/installing/manual_install).
+As of October 2011, they rely on a small program created by mySociety called
+`run-with-lockfile`. A discussion of where the source for this can be found,
+and possible alternatives, lives in
+[Alaveteli issue #112](https://github.com/mysociety/alaveteli/issues/112).
+
+## Webserver configuration
+
+We recommend running your site behind
+[Apache](https://httpd.apache.org) +
+[Passenger](https://www.phusionpassenger.com). Refer to the
+[installation instructions]({{ site.baseurl }}docs/installing/manual_install)
+regarding `PassengerMaxPoolSize`, which you should
+experiment with to match your available RAM. It is very unlikely that you'll
+ever need a pool larger than [Passenger's
+default](http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengermaxpoolsize_lt_integer_gt) of 6.
+
+We recommend you run your server behind an HTTP accelerator like
+[Varnish](https://www.varnish-cache.org).
+Alaveteli ships with a
+[sample varnish VCL](https://github.com/mysociety/alaveteli/blob/master/config/varnish-alaveteli.vcl).
+
+## Security
+
+You _must_ change all key-related [config settings]({{ site.baseurl }}docs/customising/config)
+in `general.yml` from their default values. This includes (but may not be limited to!)
+these settings:
+
+* [`INCOMING_EMAIL_SECRET`]({{ site.baseurl }}docs/customising/config/#incoming_email_secret)
+* [`ADMIN_USERNAME`]({{ site.baseurl }}docs/customising/config/#admin_username)
+* [`ADMIN_PASSWORD`]({{ site.baseurl }}docs/customising/config/#admin_password)
+* [`COOKIE_STORE_SESSION_SECRET`]({{ site.baseurl }}docs/customising/config/#cookie_store_session_secret)
+* [`RECAPTCHA_PUBLIC_KEY`]({{ site.baseurl }}docs/customising/config/#recaptcha_public_key)
+* [`RECAPTCHA_PRIVATE_KEY`]({{ site.baseurl }}docs/customising/config/#recaptcha_private_key)
+
+You should consider running the admin part of the site over HTTPS. This can be
+achieved with rewrite rules that redirect URLs beginning with `/admin`.
+
+## Email configuration
+
+See the [configuration for exim or postfix]({{ site.baseurl }}docs/installing/email/) for
+setting up your Mail Transfer Agent (MTA). It is possible to use other MTAs &mdash;
+if you use a different one, the documentation there should provide you with
+enough information to get started. If this applies to you, please add to the
+documentation!
+
+On a live server, you should also consider the following, to increase the
+deliverability of your email:
+
+* Set up [SPF records](http://www.openspf.org/) for your domain
+* Set up <a
+ href="http://en.wikipedia.org/wiki/Feedback_loop_(email)#Feedback_loop_links_f
+ or_some_email_providers">feedback loops</a> with the main email providers
+ (Hotmail and Yahoo! are recommended)
+* Especially if deploying from Amazon EC2, use an external SMTP relay for
+ sending outgoing mail. See [Alaveteli EC2 AMI]( {{ site.baseurl }}docs/installing/ami)
+ for more suggestions.
+
+## Backup
+
+Most of the data for the site lives in the production database. The exception
+is the raw incoming email data, which is stored on the filesystem, as specified
+in the setting
+[`RAW_EMAILS_LOCATION`]({{ site.baseurl }}docs/customising/config/#raw_emails_location)
+setting in `config/general.yml`.
+
+Refer to the [Postgres
+documentation](http://www.postgresql.org/docs/8.4/static/backup.html) for
+database backup strategies. The most common method is to use `pg_dump` to
+create a SQL dump of the database, and backup a zipped copy of this.
+
+Raw emails would be best backed up using an incremental strategy.
+[Rsync](http://rsync.samba.org/) is one way of doing this.
+
+Another belt-and-braces backup strategy is to set up your MTA to copy all
+incoming and outgoing mail to a backup mailbox. One way of doing this with exim
+is to put the following in your exim config:
+
+ system_filter = ALAVETELI_HOME/config/exim.filter
+ system_filter_user = ALAVETELI_USER
+
+And then create a filter file at `ALAVETELI_HOME/config/exim.filter`, with
+something like:
+
+ if error_message then finish endif
+ if $header_to: contains "mydomain.org"
+ then
+ unseen deliver "backup@mybackupdomain.org"
+ endif
+
+ if $sender_address: contains "mydomain.org"
+ then
+ unseen deliver "backup@mybackupdomain.org"
+ endif
+
diff --git a/docs/running/states.md b/docs/running/states.md
new file mode 100644
index 000000000..73e49eba7
--- /dev/null
+++ b/docs/running/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">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">FOI law</a> in your own jurisdiction). But if you do need to
+customise them, you can &mdash; see
+<a href="{{ site.baseurl }}docs/customising/themes">Customising the request states</a> for details.
+
+## WhatDoTheyKnow example
+
+Requests made on the UK's Alaveteli instance, [WhatDoTheyKnow](http://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/running/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 &#8220;Internal review of&#8221; 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/running/states_informatazyrtare.md b/docs/running/states_informatazyrtare.md
new file mode 100644
index 000000000..8097244c5
--- /dev/null
+++ b/docs/running/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 &mdash; 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">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/running/states/#awaiting_description">awaiting_description</a>
+ * <a href="{{ site.baseurl }}docs/running/states/#gone_postal">gone_postal</a>
+ * <a href="{{ site.baseurl }}docs/running/states/#internal_review">internal_review</a>
+ * <a href="{{ site.baseurl }}docs/running/states/#user_withdrawn">user_withdrawn</a>
+ * <a href="{{ site.baseurl }}docs/running/states/#waiting_response_very_overdue">waiting_response_very_overdue</a>
+
+For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}docs/running/states)) for details.
+
+
+---
+
+&nbsp;
+
+### Details of InformataZytare states
+
+The states which aren't represented on [WDTK's states]({{ site.baseurl }}docs/running/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>
+