diff options
Diffstat (limited to 'docs/running')
| -rw-r--r-- | docs/running/admin_manual.md | 969 | ||||
| -rw-r--r-- | docs/running/bodies_and_contacts.md | 194 | ||||
| -rw-r--r-- | docs/running/example_press_releases.md | 316 | ||||
| -rw-r--r-- | docs/running/index.md | 44 | ||||
| -rw-r--r-- | docs/running/promotion.md | 512 | ||||
| -rw-r--r-- | docs/running/staff.md | 18 | ||||
| -rw-r--r-- | docs/running/surveys.md | 175 | ||||
| -rw-r--r-- | docs/running/users.md | 165 |
8 files changed, 2393 insertions, 0 deletions
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md new file mode 100644 index 000000000..459449a4f --- /dev/null +++ b/docs/running/admin_manual.md @@ -0,0 +1,969 @@ +--- +layout: page +title: FixMyStreet Administrator's Manual +author: dave +--- + + +# Administrator's Manual + +<p class="lead">What is it like running a FixMyStreet 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 site, <a +href="https://www.fixmystreet.com/">fixmystreet.com</a>.</p> + +## About this document + +We'll be giving suggestions and examples of problems from our experience in +the UK. But there is more than one way to solve issues, and you may well find +that your own solutions work best. + +We hope that you will contribute to this document with your own ideas and +feedback. You can do this by [contacting us](https://www.mysociety.org/contact/) +directly, or joining the mailing list. + +The [FixMyStreet mailing list](/community) is a great place to share ideas or +ask questions. Everyone on there has either built, or is building, a +FixMyStreet site, so they have real-life knowledge and are keen to help. + +It's a friendly community, and we recommend that you join in and ask as many +questions as you need to. + +## Other helpful documents + +* **Before** you decide to run FixMyStreet, you should read the + ["Can we fix it?" DIY Guide]({{ "/The-FixMyStreet-Platform-DIY-Guide-v1.1.pdf" | relative_url }}). + +* If you are hosting FixMyStreet yourself, you **must** read the [installation + instructions](/install) first. Once you've done that, you'll probably need + the information about [customising your site](/customising) too. + +* This guide is just one of several useful pages for <a + href="{{ "/glossary/#administrator" | relative_url }}" class="glossary__link">administrators</a> in the + section about [running FixMyStreet](/running). This document is the most + general, so is a good place to start. + +## Find your administrator + +Every FixMyStreet site needs an <a href="{{ "/glossary/#administrator" | relative_url }}" +class="glossary__link">administrator</a>. Even when the site is running smoothly, +your users will need help, and there will be regular administrative tasks to +perform. So, sooner rather than later, you will need to think about who will +be responsible. + +<div class="attention-box info"> + If you're just starting on your FixMyStreet project, it's possible that you + have not found an administrator yet, or that you didn't realise you needed + one. Don't worry! Look through this document to see why you need one, and + what sort of tasks they'll be doing. +</div> + +## Who do I need? + +The team who sets up the site and those who keep it running day-to-day might +(or might not) be the same people. + +**To set up a new installation**, we recommend you have at least **one +developer** and **one administrator** who can work on the site. + +At the beginning you'll be quite busy. You'll be doing a lot of things, like +customising your site, collecting the email addresses your users' <a +href="{{ "/glossary/#report" | relative_url }}" class="glossary__link">problem reports</a> will be sent to, +and perhaps [promoting your project]({{ "/running/promotion/" | relative_url }}). + +**Once your site is up and running**, you can manage with just **one +administrator**. + +The administrator deals with problems and questions from users - we call this +'user support'. He or she will also answer questions from the bodies you send +your reports to. + +Each day, the administrator of mySociety's UK FixMyStreet site spends, on +average, between 15 minutes and an hour on user support. + +Ideally, your administrator will work every day, as there may be urgent +requests (see "Types of tasks", below). But if you cannot manage this, a +couple of sessions a week will be sufficient. + +Our administrator usually checks support emails twice a day, in the morning +and at lunchtime. This breaks the work into very short blocks, but also +ensures that she can deal with any urgent problems promptly. + +## The administration pages ("admin") + +### Security + +By default, the administration pages — the "admin" — can be found at +`/admin`. These pages must be secured against public access. + +We strongly recommend you access your admin over a secure connection, such as +HTTPS. This means that everything that goes between your computer and the +server is encrypted, so can't easily be intercepted. + +It's also a good idea to allow access to admin only from your own, trusted IP +addresses. + +Both of these precautions require system configuration (that is, they depend +on settings outside FixMyStreet). If you're running an Apache webserver, you +can do this using `htauth` — see [the Apache htauth +documentation](http://httpd.apache.org/docs/current/mod/mod_authn_file.html). +If you're using an external hosting service, their technical support staff may +be willing set this up for you if you can't do it yourself. + +It's very important that you do secure your admin: so if you really do have +problems setting this up, [get in touch](/community/) and we'll try to help. + +### Contents + +The Admin interface is divided into the following sections. You can access +them by clicking on the link at the top of any admin page: + +* **Summary page** <br/> The summary page shows the number of live <a + href="{{ "/glossary/#report" | relative_url }}" class="glossary__link">reports</a>, <a + href="{{ "/glossary/#update" | relative_url }}" class="glossary__link">updates</a>, <a + href="{{ "/glossary/#alert" | relative_url }}" class="glossary__link">alerts</a>, sent + <a href="{{ "/glossary/#survey" | relative_url }}" class="glossary__link">questionnaires</a> and + bodies' <a href="{{ "/glossary/#contact" | relative_url }}" class="glossary__link">contacts</a>. + + <p> + This page is useful when the media ask how many reports your site has + processed. You can also use it to motivate your team, or to prove yourself + to official bodies. + </p> + +* **Bodies** <br/> <a href="{{ "/glossary/#body" | relative_url }}" class="glossary__link">Bodies</a> are the + authorities that your site sends reports to. Each body has its own page in + the admin, listing the categories of problem that they accept (eg, potholes, + street lights, etc) and the email address associated with the category. + + <p> + Bodies sometimes change their email addresses, and dealing with this is a + regular task for an administrator. You can add or edit bodies from these + pages. You can also add or edit their <a href="{{ "/glossary/#category" | relative_url }}" + class="glossary__link">categories</a> and <a href="{{ "/glossary/#contact" | relative_url }}" + class="glossary__link">contact</a> email addresses. Bodies are associated with + one or more <a href="{{ "/glossary/#area" | relative_url }}" class="glossary__link">areas</a>. <a + href="{{ "/running/bodies_and_contacts/" | relative_url }}">More information on bodies</a>. + </p> + +* **Reports** <br/> The reports page lets you search for, and edit <a + href="{{ "/glossary/#report" | relative_url }}" class="glossary__link">problem reports</a> and updates. + + <p> + You will need to do this often - for example, when a user has emailed to + complain about a report, or to ask you to check if the report has been + sent. + </p> + <p> + You can search by the user's name, email address, or a word or phrase from + the report. + </p> + <p> + If your database is very large — like the UK FixMyStreet, which has many + thousands of reports — some searches may be a little slow. But if you + know the ID of the report, you can tell FixMyStreet to find it directly, + using <code>id:</code> first. The ID is in the URL of the live report: for + example, on our site, we can find + <code>https://www.fixmystreet.com/report/391267</code> by searching for + <code>id:391267</code>. + </p> + +* **Timeline** <br/> The timeline is a log of FixMyStreet activity: report + updates, status changes, and so on. + +* **Survey** <br/> By default, FixMyStreet sends out <a + href="{{ "/glossary/#survey" | relative_url }}" class="glossary__link">surveys</a> (also called + questionnaires) to users four weeks after they reported a problem. + + <p> + We use these surveys to collect data on the performance of the bodies. The + survey page shows statistics based on the responses, which again can be + useful for the media, or for research when you are looking at how + effective your site has been. + </p> + <p> + If you don't want your FixMyStreet site to send out surveys, you can + switch off this behaviour in a <a + href="{{ "/customising/cobrand-module/" | relative_url }}">cobrand module</a>. + </p> + +* **Users** <br/> You can [manage users](/running/users) from this section. + For example you can edit a <a href="{{ "/glossary/#user-account" | relative_url }}">user's</a> + email address, or <a href="{{ "/glossary/#flagged" | relative_url }}" class="glossary__link">flag</a> or + <a href="{{ "/glossary/#abuse-list" | relative_url }}" class="glossary__link">ban</a> or abusive one. + + <p> + Each user has an individual page in the admin, and it is sometimes quicker + to search for a user than a report, if they have contacted you by email + and have not mentioned which report they are talking about. Each user's + page lists all their activity on the site. + </p> + <p> + By default, any staff users (those that belong to a body) are listed on + this page. + </p> + +* **Flagged** <br/> You can <a href="{{ "/glossary/#flag" | relative_url }}" + class="glossary__link">flag</a> any report or user. This does not <a + href="{{ "/glossary/#abuse-list" | relative_url }}" class="glossary__link">ban</a> the user or delete the + report - it is just a way of marking a person or a situation as potentially + troublesome. Note that you can only flag a report or user from the report + or page. + + <p> + This can be useful if your team has more than one <a + href="{{ "/glossary/#administrator" | relative_url }}" class="glossary__link">administrator</a>. <a + href="{{ "/running/users/" | relative_url }}">More information about managing users</a>. + </p> + +* **Stats** <br/> The stats page lets you analyse the number and types of <a + href="{{ "/glossary/#report" | relative_url }}" class="glossary__link">report</a> over a particular date + range. Optionally, you can restrict it to report on a single <a + href="{{ "/glossary/#body" | relative_url }}" class="glossary__link">body</a>. + + <p> + You might use this if you want to know how many reports have been sent + within, for example, the last three months, or how many reports have been + sent to a specific body since launch. + </p> + +* **Configuration** <br/> This page shows you a summary of the live + configuration information for your site. + +<a name="report-states"></a> + +## Report states + +A <a href="{{ "/glossary/#report" | relative_url }}" class="glossary__link">problem report</a> can be in +one of these <a href="{{ "/glossary/#state" | relative_url }}" class="glossary__link">states</a>: + +<dl class="reveal-on-click" data-reveal-noun="report states"> + <dt> + Unconfirmed + </dt> + <dd> + <p> + Until FixMyStreet is certain that the report's creator is genuine, its + state remains <em>unconfirmed</em>. Unconfirmed reports do not appear on + the website. A report is confirmed (and its state becomes <em>open</em>) + when: + </p> + <ul> + <li> + its creator clicks on the link in FixMyStreet's confirmation email, or + </li> + <li> + its creator was already logged in when the report was created, or + </li> + <li> + an <a href="{{ "/glossary/#administrator" | relative_url }}" + class="glossary__link">administrator</a> confirms it (by searching in + <strong>Reports</strong> and changing the state by clicking + <strong>edit</strong>). + </li> + </ul> + </dd> + <dt> + Open + </dt> + <dd> + <p> + An <em>open</em> report is one that has not been fixed or closed. This + generally means that the body has not yet attended to the problem. Also, + this implies that the report is not <em>unconfirmed</em> (see above). <a + href="{{ "/glossary/#staff-user" | relative_url }}" class="glossary__link">Staff users</a> can set + problems to have alternative "open" states, which by default are: + </p> + <ul> + <li> + <em>investigating</em> + </li> + <li> + <em>in progress</em> + </li> + <li> + <em>action scheduled</em> + </li> + </ul> + <p>This list of states can be edited in the admin interface.</p> + </dd> + <dt> + Fixed + </dt> + <dd> + <p> + <em>Fixed</em> reports are marked in two possible ways: + </p> + <ul> + <li> + <em>fixed - user</em> + <br> + If a user marks them as fixed in an <a href="{{ "/glossary/#update" | relative_url }}" + class="glossary__link">update</a>, or (for the report creator only) as part + of the process of answering the 4-week <a href="{{ "/glossary/#survey" | relative_url }}" + class="glossary__link">survey</a>. + </li> + <li> + <em>fixed - council</em> + <br> + If updated by a <a href="{{ "/glossary/#staff-user" | relative_url }}" class="glossary__link">staff + user</a> from the body responsible for that report. + </li> + </ul> + </dd> + <dt> + Closed + </dt> + <dd> + <p> + A <a href="{{ "/glossary/#staff-user" | relative_url }}" class="glossary__link">staff user</a> + associated with the report's body (or an <a + href="{{ "/glossary/#administrator" | relative_url }}" class="glossary__link">administrator</a>) can + mark a report as <em>closed</em> without declaring it to be + <em>fixed</em>. Possible states by default are: + </p> + <ul> + <li><em>no further action</em></li> + <li><em>not responsible</em></li> + <li><em>duplicate</em></li> + <li><em>internal referral</em></li> + </ul> + <p>This list of states can also be edited in the admin interface.</p> + </dd> + <dt> + Hidden + </dt> + <dd> + <p> + Reports can be hidden by an <a href="{{ "/glossary/#administrator" | relative_url }}" + class="glossary__link">administrator</a>, or (if the <a + href="{{ "/glossary/cobrand" | relative_url }}" class="glossary__link">cobrand</a> allows it) by a <a + href="{{ "/glossary/#staff-user" | relative_url }}" class="glossary__link">staff user</a> associated + with the body to which it was sent. + </p> + <p> + Hiding a report means that it is unpublished, and can no longer be seen + on the live site - usually because it is abusive or inappropriate. + Hidden reports remain in the database, and can be republished if + necessary. + </p> + <p> + Remember that a hidden report will probably have been sent to the <a + href="{{ "/glossary/#body" | relative_url }}" class="glossary__link">body</a> responsible (so it can + still be fixed) — hiding a report simply prevents it being displayed. + </p> + </dd> +</dl> + +## Types of Tasks + +There are two main types of tasks for FixMyStreet <a +href="{{ "/glossary/#administrator" | relative_url }}" class="glossary__link">administrators</a>. + +* **Maintenance** tasks can be fixed through the FixMyStreet admin interface. + +* **User support** is generally handled by email. + +The most common maintenance tasks are described below, based on our own +experience with the UK site. + +<dl class="reveal-on-click" data-reveal-noun="types of task"> + <dt> + Bounce-backs / dead email addresses from the bodies + </dt> + <dd> + <p> + When FixMyStreet sends a <a href="{{ "/glossary/#report" | relative_url }}" + class="glossary__link">problem report</a> to the <a href="{{ "/glossary/#body" | relative_url }}" + class="glossary__link">body</a> responsible, sometimes that email bounces + back. This usually means the <a href="{{ "/glossary/#contact" | relative_url }}" + class="glossary__link">contact</a> email address you've got for that body (and + that <a href="{{ "/glossary/#category" | relative_url }}" class="glossary__link">category</a>) is + wrong, or has changed. + </p> + <p> + You can tell which report — and which body and category — + caused the problem by looking at the returned email. + </p> + <p> + Then, in admin, go to <strong>Bodies</strong> and look at the contact + email addresses for that body. Check that the email address looks + correct (for example, if there are several, see if they adhere to the + same format). + </p> + <p> + If everything looks OK, you can check online to see if you can find a + better address. Otherwise, you'll need to contact the body and confirm + the correct email address to use. + </p> + <p> + Sometimes the email address may be correct, but there's another problem + which prevents it receiving the email (such as a full mailbox). Be sure + to check the error message that the mail server returned in the + bounce-back message. + </p> + <p> + When you have found the correct email address, make sure that you + re-send the report which bounced. And if you can't find an address, you + should contact the user to let them know that unfortunately you couldn't + deliver their report. + </p> + </dd> + <dt> + Removing personal data from reports or making them anonymous + </dt> + <dd> + <p> + Sometimes people include personal details such as their address in their + report. Or they forget to tick the box to make their reports anonymous. + Sometimes a user decides to make their report anonymous after they have + submitted it. + </p> + <p> + In all cases, you can edit the report in admin by going to + <strong>Reports</strong>. Find the report you want, then click on + <strong>Edit</strong>. + </p> + <p> + Remove the details that should not be shown (we recommend replacing them + with something like “[address removed, but sent to + <em>name-of-body</em>]”). + </p> + <p> + If necessary, you can mark the report as anonymous with the yes/no + selection box. + </p> + <p> + Be sure to save your changes (click <strong>submit changes</strong>) + when you've finished editing. + </p> + </dd> + <dt> + Removing reports when users say they didn't realise their report would be + public + </dt> + <dd> + <p> + Occasionally people who are reporting issues don't understand that the + site is public, and they don't want their name associated with the + report. + </p> + <p> + In the UK, mySociety's first step is to anonymise the report. If the + user insists that the report must be removed, you can hide it instead - + then let your user know that you've made the changes they asked for. + </p> + <p> + We're generally happy to hide such reports because we don't want to + anger our users. And although this removes them from the website, the + problem report will still have been sent to the body responsible. + </p> + </dd> + <dt> + Removing inappropriate reports + </dt> + <dd> + <p> + There is a 'report abuse' link at the foot of every report, which any + user can use to alert you to a report. You will sometimes receive emails + to tell you that a report or update is inappropriate or potentially + libellous. + </p> + <p> + UK law states that we can be held legally responsible for the content, + but only if we have been made aware of it. You should make yourself + familiar with the law in your own jurisdiction, and how it may affect + your liability. + </p> + <p> + In most cases, if a report has been brought to your attention, you + should hide it - unless there is clearly nothing wrong with it. + </p> + <p> + Abuse report emails contain the admin URL of the problem report, so you + can click on it and change its state to <em>hidden</em>. + </p> + <p> + It's generally a good idea to then tell the user who reported the abuse + that you have removed it. You may also wish to contact the abusive site + member to explain why their report has been removed. + </p> + </dd> + <dt> + Users who send a report to the support email address + </dt> + <dd> + <p> + On the UK FixMyStreet site we are careful to explain that we are an + independent organisation, and we do not fix street problems ourselves. + </p> + <p> + But we still frequently receive email that should have gone to a local + council. In other words, people click on the 'support' button and submit + a report, rather than going through the normal report-making process on + the site. + </p> + <p> + We send a carefully-worded response like this: + </p> + <div class="correspondence"> + <p> + You have emailed the technical support team behind FixMyStreet, when + it looks as though you intended your message to go to your council. + FixMyStreet is an independent website through which you can contact + any council in the UK. + </p> + <p> + If you wish to report a problem please visit www.fixmystreet.com and + enter a postcode or street name near where the problem is located. You + will then be invited to click on a map to show where the problem is + occurring. + </p> + <p> + Your message is below so that you can copy and paste it into the form. + *Note that all messages appear on our website, as well as going to the + council*. + </p> + <p> + If you are able to take the time to let us know why you emailed this + address rather than file a report on the site, it would really help us + to make the process clearer for future users. + </p> + </div> + <p> + You are welcome to adapt this text to your own site's needs. + </p> + </dd> + <dt> + Manually changing users' email addresses </dt> + <dd> + <p> + Users cannot change their email addresses themselves. In admin, go to + <strong>Users</strong>, find the user (search by their name or the old + email address) and edit the email address to be the new one. + </p> + </dd> +</dl> + +## Common user support queries + +Here is a list of the most common user support queries we get on the UK +FixMyStreet site. + +<dl class="reveal-on-click" data-reveal-noun="support queries"> + <dt> + A body wants to know what email addresses you have on file + </dt> + <dd> + <p> + In the UK, it's common for each body to have multiple <a + href="{{ "/glossary/#contact" | relative_url }}" class="glossary__link">contacts</a> (usually email + addresses) — for more information, see <a + href="{{ "/running/bodies_and_contacts/" | relative_url }}">About bodies and contacts</a>. Your + site may be the same. + </p> + <p> + Often, a body will make contact to ask where your reports are being + sent. Perhaps they are changing addresses, or they are puzzled because + they can see reports on the site but don't know who is receiving them. + </p> + <p> + It's worth being friendly and helpful - if you have a good relationship + with the body, they will inform you when their contact details change, + and are more likely to treat your users' reports with respect. + </p> + <p> + Note that you can quickly copy and paste all email addresses for a body + by clicking on <strong>text only version</strong> on that body's page. + </p> + </dd> + <dt> + Body replies to you, not the user + </dt> + <dd> + <p> + This can happen if the body has set up their auto-response system + incorrectly, for example, the body has used your support email address + instead of responding directly to a user. + </p> + <p> + Forward the email to the user. Let the body know you've had to do this, + and point out the correct email address to use (FixMyStreet sends its + emails with the reply-to field set to that of the user who reported the + problem). + </p> + </dd> + <dt> + Press enquiries or data/statistic enquiries + </dt> + <dd> + <p> + Currently any requests for data or statistics that cannot be seen on the + admin summary page have to be handled by a developer, by making SQL + queries directly on the database. + </p> + <p> + <a href="{{ "/glossary#staff-user" | relative_url }}" class="glossary__link">Staff users</a> can see + the <a href="{{ "/glossary#dashboard" | relative_url }}" class="glossary__link">dashboard</a> for + their own body by going to <code>/dashboard</code> when they are logged + into the public site. If they don't have a staff user set up, offer to + do this for them: see <a href="{{ "/running/users/" | relative_url }}">managing users</a>. + </p> + </dd> + <dt> + User needs help on how to make a report on the site + </dt> + <dd> + <p> + Sometimes you may get an email from a user saying the site isn't + working, or they can't use it. Remember that your users come from all + sectors of society, including the very elderly or those who are not used + to computers. + </p> + <p> + You will often need to write back to clarify the problem. Ask for as + much detail as possible about their operating system and browser - in + simple words - and ask them to describe the issue precisely. + </p> + <p> + Often there is no problem with the site (although you should never be + certain of that until you have checked). Maybe the user has not seen the + submit button, or doesn't understand how to upload a photo, or has not + understood how the site works for some other reason. + </p> + <p> + Step-by-step instructions by email can almost always help. + </p> + </dd> + <dt> + User does not receive report confirmation email + </dt> + <dd> + <p> + <strong>This is almost always because the automated confirmation email + has gone into the user's spam folder</strong>. + </p> + <p> + Ask the user to look in their spam folder (and mark email coming from + your domain as "not spam" so future emails don't get caught in the same + way). If they still can't find it, you can confirm the report from + within admin (see <a href="#report-states">Report States</a>, above). + </p> + <p> + If you're running FixMyStreet on your own server, you (or your system + administrator) can check your outgoing email logs to confirm that the + user's mail server accepted delivery from your end. + </p> + </dd> + <dt> + User wants to know how to change their password + </dt> + <dd> + <p> + Users don't need a password to use FixMyStreet - they can click the link + in the confirmation email instead. But if a user makes a large number of + reports, it makes sense to have a password. If they are logged into the + site, they do not have to confirm reports via the email link. + </p> + <p> + Any user can set a new password at any time. + </p> + <p> + We send this response to requests to change the password: + </p> + <div class="correspondence"> + When you next create a problem report or update, simply choose the + option that says 'No, let me confirm by email'. You will be able to + create a new password at that point. This will send you a confirmation + email. Clicking the link in that email will update your password for + you. + <p> + Alternatively, you can visit https://www.fixmystreet.com/auth and do + the same (that is, choose the 'no' option and input your new + password). + </p> + </div> + <p> + Of course, make sure you change the URL in that message to match your + own installation. + </p> + <p> + Note that there's no need to provide the old password, because the + change requires the user to click on the confirmation link in the email. + </p> + </dd> + <dt> + User wants to edit their problem report + </dt> + <dd> + <p> + A user cannot change their message once they have submitted it — and + remember that the report will have already been sent to the body + responsible. + </p> + <p> + However, if there is a good case for changing the post on the website, + you can do this in the admin. Go to <strong>Reports</strong>, find the + report you want, and click on <strong>Edit</strong>. + </p> + <p> + Be sure to save your changes (click <strong>submit changes</strong>) + when you've finished editing. + </p> + </dd> + <dt> + User requests a new feature or reports a bug + </dt> + <dd> + <p> + You can log feature requests and bug reports by submitting (or, if you + prefer, by asking your developer to submit) an issue to the public + FixMyStreet <a + href="https://github.com/mysociety/fixmystreet/issues">GitHub + repository</a>. + </p> + <p> + Always search the issues first to check that it hasn't already been + raised. If it has, you can add a comment noting that it's been requested + again by another user. + </p> + <p> + When users in the UK contact FixMyStreet support with a request for a + new feature, we also reply to thank the person for taking an interest in + the site. We really do change FixMyStreet in response to user feedback! + </p> + </dd> + <dt> + User can't find a relevant category for their problem + </dt> + <dd> + <p> + FixMyStreet constructs the list of <a href="{{ "/glossary/#category" | relative_url }}" + class="glossary__link">categories</a> of report (for example, "Pothole" or + "Graffiti") based on what services the body (or bodies) <em>in that <a + href="{{ "/glossary/#area" | relative_url }}" class="glossary__link">area</a></em> provide. See <a + href="{{ "/running/bodies_and_contacts/" | relative_url }}">Managing bodies and contacts</a> to + see how this works. + </p> + <p> + This has two important consequences: it means the list of categories may + be different depending on <em>where</em> the user is reporting the + problem, and it means that sometimes the category the user wants is not + available. + </p> + <p> + When you add categories for the bodies in your FixMyStreet installation, + you should consider adding an "Other" category — provided, of course, + that the body has a general email address for such requests to go to. + </p> + <p> + Be careful, though, because if multiple bodies at the same location + offer a category called "Other", FixMyStreet — correctly — will send + such reports to all of them. + </p> + <p> + To understand more about about this, see <a + href="{{ "/running/bodies_and_contacts/" | relative_url }}">Managing bodies and contacts</a>. + </p> + </dd> + <dt> + Report has gone to wrong body + </dt> + <dd> + <p> + Sometimes a report is sent to the wrong body because the user has placed + the pin wrongly, putting the report in a different administrative + jurisdiction. Or perhaps the user has chosen the wrong category, routing + the report to a different body. + </p> + <p> + mySociety replies to the user asking them to resubmit the report with + the pin more correctly positioned, or the right category selected. + </p> + <p> + This problem may indicate that the boundary data you are using is either + incorrect, or not accurate enough — for more information, see <a + href="{{ "/customising/fms_and_mapit/" | relative_url }}">How FixMyStreet uses MapIt</a>. + </p> + </dd> + <dt> + User wants to unsubscribe from local alerts + </dt> + <dd> + <p> + Alerts are sent as emails: there's an unsubscribe link at the foot of + each one, so usually you just need to point this out politely. + <!-- TODO should be able to unsubscribe them in the admin --> + </p> + </dd> + <dt> + User just wants to send praise or thanks + </dt> + <dd> + <p> + It's nice to hear! mySociety's FixMyStreet administrator shares these + with the team and will always write back to the user to thank them. + </p> + </dd> + <dt> + The maps are out of date because there's been new development in the + user's area + </dt> + <dd> + <p> + Your FixMyStreet installation will normally be using maps from an + external source — by default this is <a href="{{ "/glossary/#openstreetmap" | relative_url }}" + class="glossary__link">OpenStreetMap</a>. + </p> + <p> + For the UK FixMyStreet, we use maps produced by the government (Ordnance + Survey), and we advise our users to contact them with any errors. Other + installations use custom maps too, so the remedy to this problem will be + different in different locations. + </p> + <p> + OpenStreetMap is an editable project, so it is possible to encourage + users — or your own team — to update the map information. It will take + a while for the map tiles to update, so these changes might not appear + on your own site immediately. + </p> + </dd> +</dl> +<div class="attention-box helpful-hint"> + <p> + A tip from Myf, who looks after the UK FixMyStreet site: + </p> + <p> + “User Support got much quicker for me once I assembled a spreadsheet with + the responses to all our most common questions and enquiries - it took a + while to put together (because I was learning the ropes) but once it was + done, I could just copy and paste, and I can now send the majority of + replies off with just a few modifications. + </p> + <p> + I'd really recommend that approach. As well as saving me time, it means I + can hand user support over to others when needed, for example, when I go + on holiday.” + </p> +</div> + +## How the site may be abused + +Any website that accepts input from the public can attract abuse - but our +experience from the UK FixMyStreet site is that it's rare. The following +section discusses some issues you should be aware of. + +### Obscene, rude or illegal material + +People may occasionally post rude, defamatory or vexatious material. Here's +our official policy from the UK FixMyStreet site: + +<div class="correspondence"> + FixMyStreet does not moderate reports before they appear on the site, and we + are not responsible for the content or accuracy of material submitted by our + users. We will remove any problem report containing inappropriate details + upon being informed, a process known as reactive moderation. Many sites + utilise this process, for example the BBC, as explained here: + <a href="http://news.bbc.co.uk/1/hi/help/4180404.stm">http://news.bbc.co.uk/1/hi/help/4180404.stm</a>. +</div> + +If a user gets in touch to complain about a report, it is sometimes because +they are offended or distressed by the content. Sometimes a report will +contain their name and address, and may be a top result when they search for +themselves on Google. + +Understandably, they may be upset or angry. Once you have made any necessary +modifications to the report - or removed it completely - you should reply +politely and calmly. Tell the user what action you have taken, and let them +know about the site policy. + +It is important to make it clear that the views our users post on FixMyStreet +are not the views of mySociety. + +We don't perform proactive moderation (that is, checking everything *before* +publishing it on the site) for two reasons. + +First, for the quantity of traffic we handle, it would be impractical. Second, +doing so would make us liable for the content under UK law. You will need to +check what the law is in your country, and how best to deal with issues such +as these. + +The FixMyStreet code *does* support moderation-before-publication, although +this is currently only enabled in the Zurich cobrand. + +### Spam reports + +Many sites which publish user-generated content suffer from spam - that is, +automated bots posting messages. + +On the UK FixMyStreet site, we do not receive many spam reports. Currently it +is almost entirely prevented by the confirmation link process. + +However, we cannot say that this will always be true, and you will need to be +aware of this possibility. + +If your site does start to suffer from spam, please share your experience with +mySociety and the community, because it's likely that solutions and responses +to the problem will be useful to everyone. + +### Silly or time-wasting reports + +Occasionally a user will post a nonsensical report, just for amusement. + +Although such things generally seem harmless, remember that, in the age of +social media, a link to amusing content can spread fast. + +In the UK, we've had one memorable case where the comedy report was publicised +in many media, and was eventually reported on the BBC website. + +You may be thinking that it's great publicity for your site, but remember that +these reports do get sent through to the bodies responsible. FixMyStreet's +role as a credible source of reports may be undermined if this happens too +often. + +Also, unfortunately, once one silly report has been made, it often gives other +users the idea to do the same. + +Consequently, on the UK FixMyStreet site we have a policy of hiding such +reports as soon as we are aware of them, to prevent other users being +encouraged to copy the behaviour. + +### Abuse: conclusion + +In practice, "problem users" are judged on a one-by-one basis. You can flag a +user or a report as problematic, and then, if they transgress again, you can +ban their email address by adding it to the "abuse list". See [managing +users](/running/users/) for details. + +It's a good idea to agree on a policy for dealing with abuse issues, and to +make sure all your administrators know what it is. + +## Software updates + +The FixMyStreet platform is under constant development. This means that new +features and improvements are made from time to time: we announce new releases +(which have version numbers) on the [fixmystreet.org blog](/blog), and on +the mailing list (see [more about staying in touch](/community)). + +Updating is a technical activity, and you'll need to log into the server's +"command shell" to do it — so ask your developer to do this for you if you're +not confident. + +If you've installed FixMyStreet as a git repository cloned from +[github.com/mysociety/fixmystreet](https://github.com/mysociety/fixmystreet) — +which will be the case if you've followed our installation instructions — +your developer should find it easy to update. Make sure they know that +sometimes these updates do require changes to the database schema too (look +for new migration files in the `db` directory). Always check the version +release notes (for example, on the blog) because we'll mention such things +there. + +## And finally... + +We wish you all the best with your FixMyStreet problem reporting site. + +If you're running an installation outside the UK please let us know by +emailing international@mysociety.org. If you have any questions, don't +hesitate to <a href="{{ "/community/" | relative_url }}">contact us</a> and we'll get back to you as +soon as possible with an answer. + diff --git a/docs/running/bodies_and_contacts.md b/docs/running/bodies_and_contacts.md new file mode 100644 index 000000000..86d06f560 --- /dev/null +++ b/docs/running/bodies_and_contacts.md @@ -0,0 +1,194 @@ +--- +layout: page +title: Bodies and Contacts in FixMyStreet +author: dave +--- + +# Managing bodies and contacts in FixMyStreet + +<p class="lead">A <strong><a href="/glossary/#body" class="glossary__link">body</a></strong> is the authority to which problem +reports will be sent. Each body needs one or more <strong><a href="{{ "/glossary/#contact" | relative_url }}" class="glossary__link">contacts</a></strong> +(typically these are email addresses) to which particular +<strong><a href="{{ "/glossary/#category" | relative_url }}" class="glossary__link">categories</a></strong> of problem are sent. </p> + +For [FixMyStreet in the UK](https://www.fixmystreet.com/), bodies are councils (county, district, and metropolitan). + +## How to add (or edit) a body + +You need access to the administration pages of your FixMyStreet installation. +By default, this is at `/admin`. + +Click on **Bodies** and fill in the form. Normally, you _must_ provide a name +and pick at least one area it covers. See [How FixMyStreet uses +MapIt](/customising/fms_and_mapit) for more information on how these areas are chosen. + +You can specify a <strong><a href="{{ "/glossary/#send-method" | relative_url }}" class="glossary__link">send method</a></strong>. This is *how* FixMyStreet will send the +problem reports to this body. + +If you leave it blank, **send method will default to email**. + +A body can have none, one, or many contacts. We strongly recommend every body +has at least one. + +## Add contacts for every category of problem this body can handle + +Even if you only have one email address for the body, you can add multiple +contacts, because each contact is for a particular **category** of problem. So +even if all the contacts' email addresses are the same, FixMyStreet treats +them separately. This often makes sense because the body passes these reports +on to different departments internally. This is also the mechanism FixMyStreet +uses to describe the category of the problem to the body: it's included, +clearly, in the email that is sent. + +Here's an example of a body and its contacts: + + Body: South Borsetshire District Council + + Contacts: + + Category Email + --------------------------------------------------- + Bridges road_department@sbdc.gov.uk + Potholes road_department@sbdc.gov.uk + Traffic lights road_department@sbdc.gov.uk + Graffiti services@sbdc.gov.uk + Street lighting lights@sbdc.gov.uk + Other enquiries@sbdc.gov.uk + +Problems about bridges, potholes, and traffic lights in South Borsetshire all +get sent to the same email address. Don't worry about the order in which the +contacts appear in the admin, because FixMyStreet sorts them before presenting +them to the user. + +The FixMyStreet admin makes it easy to change your setup if the body changes +its email addresses or even adds a new department after your site is running. + +<div class="attention-box warning"> +<h3>A body with no contacts will never receive any reports</h3> +<p> +We do not recommend you run your installation of FixMyStreet with bodies that +have no contacts. Problems submitted to such a body will remain on the site +but will not be sent. Problems like this may never get fixed. +</p> +<p> +You really need to find at least one working contact for each body to which +you want to send reports. This isn't a technical problem, but it can be one of +the more difficult parts about setting up FixMyStreet. +</p> +</div> + +### Normally, contacts use email addresses + +In most new installations, each contact needs an email address because +FixMyStreet will send the problem report to the body by email (that's the +default **send method** for bodies). Make sure you enter the correct email +address! Note that the public users of FixMyStreet do not automatically see +these email addresses, because FixMyStreet sends them directly to the body and +not to the user. + +If you're only using email as the send method (which is by far the most +common), you don't need to provide any more data (such as endpoints or API +keys). These fields are for alternatives to email. + +### Alternatives to email addresses + +Although the default method for sending reports is email, there are other ways +of sending the reports. Note, though, that alternatives to email are only +possible if the body to which you are trying to send reports supports them. +Some do; many do not. + +See +[more about integration]({{ "/customising/integration/" | relative_url }}) +to understand the different ways this can work. The first stage of +integration is injecting problem reports directly into the body's back-end +system. + +We like +<a href="{{ "/glossary/#open311" | relative_url }}" class="glossary__link">Open311</a>, +which is an open standard for +submitting problem reports to a body automatically (by sending the data +directly to a webservice that consumes it). FixMyStreet also has a number of +other, custom, methods for submitting data that we've written for specific +councils in the UK: if you need to write your own, look at the code or ask us +to help you. Custom integrations can sometimes be difficult, depending on how +easy it is to get data in and out of the body's internal, back-end systems. + +You can change a body's send method -- for example, if you start by sending +emails, but then discover the body is running an Open311 server, it's easy to +change over. Note that if you choose a different send method, FixMyStreet will +need some extra information, such as the URL of the body's endpoint. This +appears on the form if it's needed. + +For more information about Open311, see [this blog post explaining +it](https://www.mysociety.org/blog/open311-explained). + +#### Not all of a body's contacts need to be sent the same way + +In fact, if you're working on an installation that can connect to bodies using +a method other than email, not *all* of a body's contacts need to be sent the +same way. It's possible to specify a different +<a href="{{ "/glossary/#send-method" | relative_url }}" class="glossary__link">send method</a> +for an individual contact. To do this you need to tell FixMyStreet that, for +this body, the decision of which send method to use can be +<a href="{{ "/glossary/#devolve" | relative_url }}" class="glossary__link">devolved</a> +to the contacts. You'll need to edit the body (in `/admin`) and check the box +marked "Contacts can be devolved". Then mark each of the contacts that are not +using the body's send method (which by default is email) as "devolved", and +specify their own send method and details. + +## Deleting contacts + +If a contact is no longer valid, you can delete it or mark it as inactive. Find +it on the body's admin page, click to edit it, and select **inactive** or +**deleted**. + +Inactive contacts can still be filtered on map pages, but deleted contacts will +not appear there at all. Neither sort of contact can be used for new reports. + +Deleted contacts are not removed from the FixMyStreet database because doing +so might break any existing problem reports that used it. + +## Deleting bodies + +It's unusual to need to delete a body, but it sometimes happens — for +example, if a body ceases to exist because it has merged with an existing +one. If this happens, remember that you may also need to create a new body, or +change the +<a href="/glossary/#area" class="glossary__link">admin boundary</a> +of an existing one. + +To delete a body, go to the body's admin page to edit it. Tick the checkbox +marked **Flag as deleted**, and then click **Update body**. + +This does not remove the body from the FixMyStreet database (because there may +be existing problem reports that depend on it). The reports, and the "deleted" +body, remain as historic data. Users cannot submit reports to a deleted body. + +<div class="attention-box warning"> + If you're testing FixMyStreet and you're sure you want to <em>really</em> + delete a body, because you just created it as test, you need to delete it + directly within the database. + You cannot do destructive deletion like this through the admin interface. + <p> + We recommend you do your testing on a + <a href="/glossary/#staging" class="glossary__link">staging site</a> + rather than + <a href="/glossary/#production" class="glossary__link">production</a>. + </p> +</div> + +In the UK, where FixMyStreet has been running for a long time, there have +been several changes to the councils that we cover. You can see deleted councils +marked in grey on [the list of councils](https://www.fixmystreet.com/reports). +We handle deleted councils as a special case because we want to direct the user +to the appropriate extant body instead. For example, see the page for +[Alnwick Council's reports](https://www.fixmystreet.com/reports/Alnwick); that +council ceased to exist in 2009. + +If you want to replicate behaviour like this on your site, copy the +`reports/_body_gone.html` template from the `fixmystreet.com` cobrand into your +own <a href="/glossary/#cobrand" class="glossary__link">cobrand</a>, +<a href="/customising/templates/">customise it</a>, and make sure you update +the body to not be associated with any area. You can do this by editing the +body, and at the **Area covered** drop-down menu making sure no areas are +selected. diff --git a/docs/running/example_press_releases.md b/docs/running/example_press_releases.md new file mode 100644 index 000000000..9a68cfd87 --- /dev/null +++ b/docs/running/example_press_releases.md @@ -0,0 +1,316 @@ +--- +layout: page +title: Example press releases +author: myf+dave +--- + +# Example press releases + +Here are templates for two types of press release: one [for national +media](#national) and one [for local media](#local). These templates show you +what to include in a standard press release. + +Adapt the wording so that it’s suitable for your project — or of course, you +may wish to write your own press releases from scratch. + +Then send it to your media contacts, as described in our +[guide to promoting FixMyStreet]({{ "/running/promotion" | relative_url }}). + +It’s best to copy and paste the text into the body of an email, rather than +send it as an attachment: journalists say that they are far more likely to read +an email than an attachment. + +<a name="national"> </a> + +## Press release 1: For national media + +<input type="button" class="toggle-button" value="Show/hide explanations" data-target="national-press-release"/> + +<div class="mock-document" id="national-press-release"> + <div class="attention-box helpful-hint"> + <p> + Headline: Put a large headline at the top; you can also use the same + wording as the title of your emails, prefaced by the words: PRESS RELEASE. + </p> + <p> + You don’t have to use this sentence, but try to think of a short + statement that will attract journalists’ attention as well as explaining + what your site will do. + </p> + </div> + + <h2><span class="replace-text">[Your site’s name]</span>: a new way to get your community fixed</h2> + + <div class="attention-box helpful-hint"> + <p> + If you would like to send your press release before launch, to give + journalists a little time to write their story, include an embargo + date/time. That means they won’t publish anything until this date. + Typically embargo times are given as 12:01am. + </p> + </div> + <h3>EMBARGO: <span class="replace-text">[Date/time]</span></h3> + + <div class="attention-box helpful-hint"> + <p> + Include the URL of your FixMyStreet site, and any other URL that’s + useful, eg your organisation’s website. + </p> + </div> + <h3>LINK/S: <span class="replace-text">[URLs]</span></h3> + + <div class="attention-box helpful-hint"> + <p> + Your name and email address/phone number + </p> + </div> + <h3>CONTACT: <span class="replace-text">[hello@example.org]</span></h3> + + <div class="attention-box helpful-hint"> + <p> + Three or four bullet points which summarise the main content of the press + release. If you have a quote from a councillor or mayor, so much the + better, but if not, it’s fine to quote yourself. + </p> + </div> + <uL> + <li> + <span class="replace-text">[Name of site]</span> launches today + </li> + </uL> + + <div class="attention-box helpful-hint"> + <p> + List the most common problems in your own country: + </p> + </div> + + <ul> + <li> + Report potholes, broken pavements and other community problems to the + authorities responsible for getting them fixed + </li> + </ul> + <ul> + <li> + “A revolution in citizen to government communication” says founder + </li> + </ul> + + <div class="attention-box helpful-hint"> + <p> + This is the main body of your press release. Keep it fairly succinct: + 5–10 paragraphs of 1–2 sentences each is plenty. You can, of + course, alter the text to make it more appropriate to your country’s own + circumstances. + </p> + </div> + + <p> + <span class="replace-text">[Name of your site]</span>, a new and simple way + for citizens to report street faults, launches today. + </p> + <p> + Most people know that it’s the council’s job to fix problems like potholes, + dangerous pavements or broken street lights. But reporting such problems + can often be a difficult task. People don’t always know which council area + they are in. Even if they do, they’re often faced with a lack of + information online, or hard-to-navigate web forms. + </p> + <p> + Now, a new website simplifies the process for people in <span + class="replace-text">[name of your country or the area that your site + covers]</span>. + </p> + <p> + With <span class="replace-text">[name of your site]</span>, a project from + <span class="replace-text">[your organisation]</span>, all the user has to + do is put a pin in a map to show where the problem is, then add a few lines + of text to describe the issue. Optionally, they can also add a photo. + </p> + <p> + <span class="replace-text">[Name of site]</span> sends the issue to the + right department of the right council: the user doesn’t even have to know + which jurisdiction they are in. From the council’s side, responding to the + problem report is as simple as replying to any other email. + </p> + <p> + Reports are already flooding in, including <span class="replace-text">[list + some interesting existing reports, with links]</span>. + </p> + <p> + <span class="replace-text">[Name of site]</span> also publishes all reports + online, eventually building into a rich resource showing what the prevalent + types of problem are in any area. The site uses the FixMyStreet Platform + open source software, which has proven effective in the UK and across more + than 20 other countries around the world. + </p> + <p> + <span class="replace-text">[Your name]</span>, <span + class="replace-text">[your job title or description]</span>, says, “<span + class="replace-text">[add a quote here]</span>”. + </p> + <p> + <span class="replace-text">[Name of site]</span> is ready to send off your + street fault reports: give it a try at <span + class="replace-text">[URL]</span>. + </p> +</div> + +<a name="local"> </a> + +## Press release 2: For regional/local media + +<input type="button" class="toggle-button" value="Show/hide explanations" data-target="local-press-release"/> + +<div class="mock-document" id="local-press-release"> + <div class="attention-box helpful-hint"> + <p> + Headline: Put a large headline at the top; you can also use the same + wording as the title of your emails, prefaced by the words: PRESS RELEASE. + </p> + <p> + You don’t have to use this sentence, but try to think of a short + statement that will attract journalists’ attention as well as explaining + what your site will do. Include the name of the local area so they can + see how relevant it is to their audience. + </p> + </div> + <h2> + <span class="replace-text">[Your site’s name]</span>: a new way to get + <span class="replace-text">[city or county name]</span> fixed + </h2> + + <div class="attention-box helpful-hint"> + <p> + If you would like to send your press release before launch, to give + journalists a little time to write their story, include an embargo + date/time. That means they won’t publish anything until this date. + Typically embargo times are given as 12:01am. + </p> + </div> + <h3> + EMBARGO: <span class="replace-text">[Date/time]</span> + </h3> + + <div class="attention-box helpful-hint"> + <p> + Include the URL of your FixMyStreet site, and any other URL that’s + useful, eg your organisation’s website. + </p> + </div> + <h3> + LINK/S: <span class="replace-text">[URLs]</span> + </h3> + + <div class="attention-box helpful-hint"> + <p> + Your name and email address/phone number + </p> + </div> + <h3> + CONTACT: <span class="replace-text">[hello@example.org]</span> + </h3> + + <div class="attention-box helpful-hint"> + <p> + Three or four bullet points which summarise the main content of the press + release. If you have a quote from a councillor or mayor, so much the + better, but if not, it’s fine to quote yourself. + </p> + </div> + <ul> + <li> + <span class="replace-text">[Name of site]</span> launches today + </li> + </ul> + + <div class="attention-box helpful-hint"> + <p> + List the most common problems in your own country: + </p> + </div> + <ul> + <li> + Now it’s simple for residents of <span class="replace-text">[city or + county name]</span> to report potholes, broken pavements and other + community problems + </li> + </ul> + + <ul> + <li> + “Let’s get <span class="replace-text">[name of city or county]</span> + fixed”, says founder + </li> + </ul> + + <div class="attention-box helpful-hint"> + <p> + This is the main body of your press release. Keep it fairly succinct: + 5–10 paragraphs of 1–2 sentences is plenty. You can, of + course, alter the text to make it more appropriate to your country’s own + circumstances. + </p> + </div> + <p> + <span class="replace-text">[Name of your site]</span>, a new and simple way + for <span class="replace-text">[city or county name]</span> to report + street faults, launches today. + </p> + <p> + Most people know that it’s the council’s job to fix problems like potholes, + dangerous pavements or broken street lights <span class="replace-text">[or + substitute the common problems in that region]</span>. But reporting such + problems can often be a difficult task. People don’t always know which + council department to contact. Even if they do, they’re often faced with a + lack of information online, or hard-to-navigate web forms. + </p> + <p> + Now, a new website simplifies the process for people in <span + class="replace-text">[city or county name]</span>. + </p> + <p> + <span class="replace-text">[Name of your site]</span>, a project from <span + class="replace-text">[your organisation]</span>, covers the whole of <span + class="replace-text">[the country/name of city]</span>, using smart + technology to send problems to the department responsible for getting them + fixed. + </p> + <p> + All the user has to do is put a pin in a map to show where the problem is, + then add a few lines of text to describe the issue. Optionally, they can + also add a photo. + </p> + <p> + <span class="replace-text">[Name of site]</span> sends the issue to the + right department of the council: the user doesn’t even have to know which + jurisdiction they are in. From the council’s side, responding to the + problem report is as simple as replying to any other email. + </p> + <p> + <span class="replace-text">[Name of site]</span> also publishes all reports + online, eventually building into a rich resource showing what the prevalent + types of problem are in any area. Residents of <span + class="replace-text">[city/county name]</span> have already reported issues + such as <span class="replace-text">[list some existing reports, with + links]</span>. + </p> + <p> + The site uses the FixMyStreet Platform open source software, which has + proven effective in the UK and across more than 20 other countries around + the world. + </p> + <p> + <span class="replace-text">[Your name]</span>, <span + class="replace-text">[your job title or description]</span>, says, “<span + class="replace-text">[add a quote here, perhaps mentioning the city or + county]</span>”. + </p> + <p> + <span class="replace-text">[Name of site]</span> is ready to send off your + street fault reports: give it a try at <span + class="replace-text">[URL]</span>. + </p> + +</div> diff --git a/docs/running/index.md b/docs/running/index.md new file mode 100644 index 000000000..e552826dd --- /dev/null +++ b/docs/running/index.md @@ -0,0 +1,44 @@ +--- +layout: page +title: Running FixMyStreet +author: dave +--- + +# Running FixMyStreet + +<p class="lead">After you've installed FixMyStreet, you need to manage the +site. The information here will help you with the common tasks needed to keep +everything running smoothly. </p> + +<div class="row-fluid"> +<div class="span6"> +<ul class="nav nav-pills nav-stacked"> +<li><a href="admin_manual/">Administrator's manual</a></li> +<li><a href="staff/">Staff user's manual</a></li> +<li><a href="bodies_and_contacts">About managing bodies and contacts</a></li> +<li><a href="users">About users</a></li> +</ul> +</div> +</div> + +## Accessing the admin pages + +By default the administration pages for FixMyStreet can be found on your +installation at `/admin`. + +When you first deploy your installation of FixMyStreet, this is just a public +directory. Obviously, for a +<a href="{{ "/glossary/#production" | relative_url }}" class="glossary__link">production</a> +server you should **restrict access to +authorised users only**. For example, if you're running the Apache webserver, +you can use `htaccess` to do this. + +<div class="attention-box warning"> + <p><strong>You <em>must</em> restrict access to admin</strong> + <br> + Never put your FixMyStreet site live until you have protected + your admin pages. + </p> +</div> + +If you can configure your webserver to only allow access to the admin URLs over https, then you should do that, and deny access any other way. It's also a good idea to IP-restrict access to admin URLs if you know where your authorised users will be accessing them from. diff --git a/docs/running/promotion.md b/docs/running/promotion.md new file mode 100644 index 000000000..d20c19695 --- /dev/null +++ b/docs/running/promotion.md @@ -0,0 +1,512 @@ +--- +layout: page +title: Promoting your FixMyStreet +author: myf +--- + +# How to promote your FixMyStreet site + +So your site is up and running, emails are going off to the right places and +everything looks good. There’s just one more thing you need: some users. + +When people think of the phrase ‘publicity campaign’, they may imagine +expensive TV advertisements, billboard posters and magazine spreads. + +But there are plenty of ways to promote your site that cost nothing, or only a +little. In this guide, we will be looking at some of the most effective ways +you can publicise your site on a low budget. + +Anyone can manage the actions we’re about to run through, and we promise they +will bring you more users. + +## Things to do before you launch + +### Four weeks before launch: make plans + +Will you have a launch party or other event? Who will you invite? Do you need +printed materials? Now is the time to get everything in place. + +*Launch parties are not vital, but if you have contacts in the media or local +government, they’re a good way to make a bit of a splash. They don’t have to be +expensive: all you need is a few snacks and a good presentation.* + +### Three weeks before launch: start filling your site with content + +When people start to visit your site, ideally it will already look like a +successful project that is getting problems fixed. + +Consider asking your friends and family to start using it before your official +launch, so that there is plenty of activity on display. + +Or invite your supporters to be ‘beta testers’, with early access to the site. +If you have a mailing list or newsletter, you can invite your subscribers. If +you prefer to keep your site protected until your launch, you can always share +the password with this small group of early users. + +If all else fails, post some reports yourself! + +### Two weeks before launch: gather media contact details + +You’ll be sending announcements to the media, so you’ll need to gather the relevant email addresses before your launch date. + +There are often useful lists of these online - search for things like ‘press contact lists’ or ‘media contacts’. + +Otherwise, most publications provide a contact page. Put together a spreadsheet of addresses that you can use to send out your press releases when the time comes. Here’s what your spreadsheet might look like at this stage: + +<table class="table promo-spreadsheet"> + <tr class="sheet-header"> + <th colspan="6">National press</th> + </tr> + <tr> + <th>Name</th> + <th>Contact</th> + <th>Email address</th> + <th>Did they write about us?</th> + <th>Link to story</th> + <th>Journalist’s name</th> + </tr> + <tr> + <td>The National News</td> + <td>James Bloggs</td> + <td>newsdesk@nationalnews.com</td> + <td> </td> + <td> </td> + <td> </td> + </tr> + <tr> + <td>The Daily Blah</td> + <td>Diana Penfold</td> + <td>diana.penfold@thedailyblah.org</td> + <td> </td> + <td> </td> + <td> </td> + </tr> + <tr> + <td><em>add more here...</em></td> + <td> </td> + <td> </td> + <td> </td> + <td> </td> + <td> </td> + </tr> + <tr class="sheet-header"> + <th colspan="6">Regional press</th> + </tr> + <tr> + <th>Name</th> + <th>Contact</th> + <th>Email address</th> + <th>Did they write about us?</th> + <th>Link to story</th> + <th>Journalist’s name</th> + </tr> + <tr> + <td>Smallton Times</td> + <td>William Whistler</td> + <td>will@smalltontimes.co.uk</td> + <td> </td> + <td> </td> + <td> </td> + </tr> + <tr> + <td>Realville Mercury</td> + <td>Editor</td> + <td>editor@themercury.co.uk</td> + <td> </td> + <td> </td> + <td> </td> + </tr> + <tr> + <td><em>add more here...</em></td> + <td> </td> + <td> </td> + <td> </td> + <td> </td> + <td> </td> + </tr> +</table> + +You can fill in the last three columns after launch. + +### One week before launch: notify councils and local authorities (perhaps) + +Consider speaking to the authorities who will be receiving your reports — +especially those who do not already have a fault-reporting system online. + +You will know best how your site is likely to be received by these authorities. +In the UK, we’ve had a variety of experiences, from a small number of councils +who don’t see the point, or dislike our service, to those who think it’s +wonderful. + +Approach councils in the right way, and they may be glad to help you advertise +your site to their residents. In any case, it’s always good to build up +relationships with these bodies, because they can keep you updated about +changes of email addresses or the different departments reports should be sent +to. + +## At launch + +Your launch day has arrived! Time to get busy. + +Hopefully, your period of beta-testing (or while your friends and family have +been using the site) will have helped you detect and solve any technical +issues, so when launch comes, you can dedicate yourself at least a couple of +days to promotion. + +### 1. Tell the media + +Newspapers and magazines, TV and radio shows — every time there’s a mention of +your new site, it will bring you users. + +FixMyStreet has a great advantage when it comes to press coverage: the overall +concept is interesting to national media, while the local aspects of the site +appeal to regional media, too. + +#### Press releases + +Send details of your launch to any outlet you think will cover it. Be clear and +concise: explain what the site is for and how it benefits users. + +Not sure how to write a press release? +[We’ve provided a template here]({{ "/running/example_press_releases" | relative_url }}). + +You may wish to send out two types of press release: + +* A release for the national media, explaining that the site covers the whole + country (if that’s the case) and that the great benefit for users is that + they don’t need to know which council is responsible for which type of + problem in which jurisdiction. + +* A release for local press, pointing out that residents in their area can now + make reports quickly and easily. You can copy and paste the name of the + region into each one, so it seems especially relevant to them. + +But be careful: when the team behind [FiksGataMi](http://fiksgatami.no), the +Norwegian FixMyStreet, sent press releases to every media outlet in the +country, it attracted so many users that their server was overwhelmed with +traffic! + +You can avoid this with load testing, which makes sure that your servers can +cope with increased amounts of traffic, or simply by sending out your press +releases at intervals, over a period of time. + +> **Pere**: We gathered the email address of every media outlet +> in Norway, and used this list to send press releases +> about the service. All local media, all national press, +> all tv stations, radio stations, technical magazine, +> everything. +> +> This overloaded the service after a few hours. +> FiksGataMi went down after 2-3 hours. +> I believe we sent the press release around 8:00 in the +> morning, it went down before 11:00, and came back online +> around 14:00. +> +> Quite a lot of local papers wrote about FiksGataMi, and +> suggested their readers used it to report problems. For +> example Adressavisa, the largest paper in the middle of +> Norway (Trondheim), published several stories over many +> days. This caused Trondheim municipality to get more +> requests than they could handle... + +### 2. Local outreach + +One of the most direct ways to publicise FixMyStreet is to take it out to the +people who will use it. + +You can do this in your own local town — and if you have friends and supporters in other towns, you can ask them to put up posters or leave leaflets in public places for people to take. + +> In the Maldives, the [MakeMyIsland](http://www.makemyisland.mv) ‘roadshow’ +> handed out leaflets on the street, and explained the service to passers-by. + +<blockquote class="twitter-tweet" lang="en"><p lang="et" dir="ltr"><a href="https://twitter.com/hashtag/MakeMyIsland?src=hash">#MakeMyIsland</a> roadshow <a href="https://twitter.com/hashtag/hapsnau?src=hash">#hapsnau</a> in Hulhumale' <a href="https://twitter.com/UNDPMaldives">@UNDPMaldives</a> <a href="https://twitter.com/InnovateAP">@InnovateAP</a> <a href="https://twitter.com/UNDPasiapac">@UNDPasiapac</a> <a href="https://twitter.com/mysociety">@mysociety</a> <a href="https://t.co/hqh6busDZr">pic.twitter.com/hqh6busDZr</a></p>— Nathu Wafir (@nathuwafir) <a href="https://twitter.com/nathuwafir/status/684358147914387456">January 5, 2016</a></blockquote> +<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> + +You could do the same: is there an area that is particularly notorious for +problems such as potholes or rubbish tipping, perhaps? That would be a good +place to chat to people. + +Print up or photocopy a few leaflets. These can be very simple and direct, so +long as they explain the concept and include the URL. Here’s a postcard that +the UK FixMyStreet has used: + +<a href="https://www.fixmystreet.com/about/posters"><img src="/assets/img/promote-90x130.png" alt="FixMyStreet postcard"></a> + +The nice thing about postcards is that they can get your message out twice: +once to the person who picks it up, and once to the person they send it to. + +Put up posters, anywhere people are likely to see them: on universities’ notice +boards, in shops and cafes, libraries... anywhere it’s allowed. + +When you design your leaflets and posters, don’t include any content that will +date (eg mentioning that the site is new and has just launched), and you will +be able to use them at other events in the future. + +## After launch + +So, you told lots of people about your FixMyStreet site, and it got lots of +interest. That’s great. + +But people have short memories, so it’s important to keep dedicating some time +to promoting your site. + +You might not have the time or resources to do everything that’s suggested +below. Why not try a couple, and see how effective they are, then try another +couple later on, and compare? That way you can find out what works best, and +where to dedicate your time. + +### Social media + +Set up accounts on whichever social media is most used in your country: in the +UK, we have FixMyStreet accounts on Twitter and Facebook. You have the option +to set up links to your social media accounts in the site’s footer, report +pages, etc: you can +[read more about customising your FixMyStreet site here]({{ "/customising/" | relative_url }}) +— or [contact us]({{ "/community/" | relative_url }}) if you need more help. + +You’ll need to monitor your accounts daily, in case people ask you questions +that need a prompt reply. The easiest way is to set up your accounts so that +you automatically receive an email every time someone mentions you. + +For Twitter, go to +[https://twitter.com/settings/notifications](https://twitter.com/settings/notifications) +to set your preferences for email alerts. + +<a href="https://twitter.com/settings/notifications"><img src="/assets/img/promo-twitter-screenshot.png" alt="Twitter settings screenshot" /></a> + +And for Facebook, go to +[https://www.facebook.com/settings?tab=notifications](https://www.facebook.com/settings?tab=notifications) +to set your preferences for alerts. Click on ‘pages you manage’ to find the +settings for your FixMyStreet page. + +<a href="https://www.facebook.com/settings?tab=notifications"><img src="/assets/img/promo-facebook-screenshot.png" alt="Facebook notifications screenshot" /></a> + +Use your social media accounts to send out regular messages to your followers. +You might: + +* Link to your most interesting (or infuriating, or puzzling, or funny) + reports. If they’re interesting enough, people will share them, helping you + publicise your site even further. +* Answer your users’ questions about how the site works. +* Find people who are complaining about their local community, and tell them + about your site. +* Generally promote your site with timely messages. In the UK, we talk about + potholes in the colder months because that is when they tend to appear; and + we remind people to report broken street lights when the clocks go back and + people are walking home in the dark. +* Things tend to get fixed more just before the elections - a cynical view, but + one that’s true. So this may be a great time to encourage people to make + reports, and highlight those that have got things fixed. + +#### Keep a blog +Let users know what enhancements you’ve made, events you’ll be at, or just what you’ve been doing lately, with regular blog posts. + +### Regular press releases + +Don’t lose that spreadsheet of media contact addresses - you’re going to need +it again. In fact, make a note on it of which outlets wrote stories about your +site, and the details of the journalists who wrote the stories, so you can +contact them directly next time. + +> **Pere**: To remind the press about our existence we’ve +> sent press releases about FiksGataMi on and off since the +> release. + +Of course, you don’t want to irritate your press contacts with over-frequent press releases, but if you make sure that you have a good story to share, many will welcome your emails. + +What makes a good story after launch? + +* **Statistics**. Use the FixMyStreet dashboard or + your Analytics programme to find out things like: + * how many reports have been made? (Check `/stats` in + your site’s admin dashboard for the overall count, or + count for specific councils/within specific timeframes) + + * what are the most frequent types of report? + (Difficult to be precise, but + `/summary?show_categories=1#category-fix-rate` + will give you a general idea) + + * which area is filing the most reports? + (Check `/reports` on your live site, but do remember + that if council areas are of different sizes or + population densities, that also affects numbers) + + * which reports are the most people viewing? + (Use your analytics programme, and filter to see URLs + containing `report/`) + +* **Unusual or funny reports**. You can use your Analytics programme to see + which reports have been most-viewed: often they are the ones with the most + human interest. + +In the UK, one of our most-viewed reports was about a rare bird which had been +spotted after it escaped from its owner. + +<a href="https://www.fixmystreet.com/report/242529"><img src="/assets/img/fms-unusual-bird-screenshot.jpg" alt="FixMyStreet screenshot: report 242529"></a> + +The UK FixMyStreet site includes [this page](https://www.fixmystreet.com/about/fun). +You might like to include something similar: it’s great to point press towards, +so long as you keep it up to date. + + +* **Success stories** Check the reports that have been marked as fixed, to see + if any of them has made a really big difference to a local community. +* **The local angle** Send local media summaries of the most common types of + report in their own area, or the numbers of reports made. +* **Local radio** In the UK, we are often invited to speak on local radio when + they are doing a feature about issues such as potholes or rubbish clearance. + Normally, we just talk for five minutes, telling people about the site and + what it does. If you have a radio network that covers all regions, contact + them to let them know that you are available as a speaker, and you may be + added to their list of people to include in such features. + +#### Tell journalists to subscribe + +You can tell local journalists about the alerts service on FixMyStreet. There +are links to instructions on setting up alerts on all map pages on the site, or +on `/alert`. + +This functionality allows anyone to subscribe to their local area, so that they +get an email every time anyone makes a report within that neighbourhood. It’s +an effort-free way of staying up to date with the issues that concern their +readers, and also means the journalists can be the first to see any potential +stories. + +> **Myf**: In the UK, we also spent a bit of time contacting very local +> publications, including parish newsletters and community magazines. Although +> each publication may only be read by a couple of hundred to a few thousand +> readers, they are really focused on their own neighbourhood, so the FixMyStreet +> message works well for them. +> +> Because such publications tend to have few staff and not much time, we provided +> them with a ready-written news story and also some graphics, so all they had to +> do was drop them into their templates. + +### Events + +Get involved with events in your area — it’s a good way to meet potential +users. Or, for most of the types of event listed below, if you can’t attend, +you could send some leaflets and posters along and ask for them to be +distributed. + +#### Community fairs, festivals, conferences and meetings + +Ask if you can have a table. Take leaflets, and a smartphone, tablet or laptop +if you have internet access. + +One very direct way to explain what FixMyStreet does is to invite people to +search the site and see the problems reported around their own home. Everyone +is interested to see what has been reported in their own community. + +Then you can guide them through the process of making a report themselves. + +Optionally, ask people for their email addresses so that you can sign them up +to a newsletter. + +#### Set up your own events + +Your local library, hall or co-working space may be glad to let you have a +room and internet access so that you can show residents how to use FixMyStreet. +Put up some posters and invite people to drop by for a fifteen-minute demo. + +#### Clubs and societies + +Certain types of societies’ members will be particularly interested in +FixMyStreet. + +Are there any associations in your country who volunteer to keep the streets +clean, or do gardening in the local parks? Local history organisations tend to +be full of people who also have an interest in keeping the community to a good +standard! Consider women’s groups, local co-operatives, church societies… and +any other groups with a stake in their community. + +> In the UK, we provided special downloadable ‘packs’ for clubs and societies: +> see the Community Group pack on <a href="https://www.fixmystreet.com/about/posters">this page</a>. + +<a href="https://www.fixmystreet.com/about/posters"><img src="/assets/img/promo-community-pack-screenshot.png" alt="FixMyStreet posters screenshot"></a> + +#### Internet-related conferences and hackdays + +FixMyStreet is for everyone to use, not just those with technical skills — but +you may find that some of your strongest supporters come from the coder +community. Because the code is open source, developers can use it to develop +their own tools, too. Perhaps they will contribute some improvements to the +main codebase. + +### Newsletter + +You might have a newsletter that goes out to all supporters of your +organisation, or one that’s specific to your FixMyStreet site. Either way, send +regular messages. If you are doing some or all of the activities listed above - +events, blog posts, news stories - you will already have content for your +newsletter; you’ll just need to link to it. + +Make sure you invite users to sign up to your newsletter. Check our +[documentation on customising your site]({{ "/customising/" | relative_url }}), +or mySociety can help you include a message about the newsletter at various +key points, like: + +* in your email alerts +* at the point when people have completed making a report +* in the footer of your site + + +### Word of mouth + +Word of mouth is an effective way of getting your site known — and it’s free. +But generally, people won’t talk about your site unless you explicitly ask them +to. + +In the UK, we created [this page](https://www.fixmystreet.com/about/posters), +with downloads of resources that help people spread the word about FixMyStreet. +They can print out posters and flyers, and there are templates for news stories +they can send to local magazines or newsletters. There are even activities for +school children and Girl Guides, Scouts, Cubs and Brownies. Feel free to copy +anything from that page and adapt it for your own site/culture/language. + +You may also wish to send this same message - “Please tell your friends about +this site” - via your email alerts, your newsletter, social media, and when you +meet users face to face. You can never ask enough! + +> **Myf**: In the UK, we took this idea one step further. We +> identified some of our site’s most prolific report-makers, +> and emailed them to congratulate them for being +> “FixMyStreet SuperUsers”. +> +> We offered to send them a tote bag and stickers which we’d +> printed up with the FixMyStreet logo, as a way of saying +> thank you — and we also sent them a large stack of +> promotional postcards, asking them to leave these in spots +> around their local town. +> +> These people were obviously already predisposed to feel +> positive about FixMyStreet, so they gladly performed what +> was, however you look at it, a task that benefited us more +> than them. + +<img src="/assets/img/promo-superuser-screenshot.png" alt="FixMyStreet superuser notice screenshot"/> + +Of course, the nice thing about a bright bag is that it also helps promote the +site as its owner carries it around. Some recipients even photographed their +bag and put them on Twitter and Instagram! + +### Online advertising + +If your organisation is a registered charity, and if you operate in one of the +eligible countries, you can apply for free Google Adwords advertising worth up +to US $40,000 per year. [Find out more here](https://www.google.co.uk/intl/en/grants/). + +mySociety can help you with setting up your account, if required, once you have +got the grant. + +### Share your experiences + +If you’ve tried any of these ideas, let us know how it went. What did you +learn? Any tips for others who are about to launch their own FixMyStreet sites? + +Maybe you have some more ideas, or can tell us how you promoted your own site. +Please share your thoughts and stories on the +[FixMyStreet mailing list](https://groups.google.com/a/mysociety.org/forum/#!forum/fixmystreet), +so that everyone can benefit from your knowledge. + diff --git a/docs/running/staff.md b/docs/running/staff.md new file mode 100644 index 000000000..77ca05c8e --- /dev/null +++ b/docs/running/staff.md @@ -0,0 +1,18 @@ +--- +layout: page +title: Staff users in FixMyStreet +author: matthew +--- + +# Staff users in FixMyStreet + +<p class="lead">Privileged accounts with access to management features.</p> + +Staff users are a middle rung of account, inbetween normal users of the site +and superusers with full access to everything. They are associated with a +particular body, and can have access to different features, depending upon the +permissions granted to them. All their abilities only apply to reports made +to the body with which they are associated; all staff users have access to all +report states, not just open/fixed. + +{% include admin-tasks-content.md %} diff --git a/docs/running/surveys.md b/docs/running/surveys.md new file mode 100644 index 000000000..fbb889b61 --- /dev/null +++ b/docs/running/surveys.md @@ -0,0 +1,175 @@ +--- +layout: page +title: FixMyStreet's surveys +author: dave +--- + +# FixMyStreet's surveys + +<p class="lead"> + By default, four weeks after a user reports a problem, FixMyStreet sends an + email inviting that user to complete a survey (which we also sometimes call a + questionnaire). The survey is presented as a page on the site that asks the + user about the current + <a href="{{ "/glossary/#state" | relative_url }}" class="glossary__link">state</a> + of the problem (for example, it may have been fixed), and lets them add an + <a href="{{ "/glossary/#update" | relative_url }}" class="glossary__link">update</a> + too. +</p> + +We recommend that you keep this feature enabled, because it gives you +useful data about the problems that have been reported on your site, and +an indication of the performance of the +<a href="{{ "/glossary/#body" | relative_url }}" class="glossary__link">bodies</a> +that should be fixing them. Some users will report a problem and then won't +really think about it after that. We're happy with this, because it's how the +site is supposed to work — reporting a problem is easy and doesn't demand +any further interaction. + +That's why sending a survey email a month later works well. It serves as a +reminder, and it helps ensure that the reports that have been fixed have their +states set accordingly. + +Of course, it's possible that the problem has already been marked as fixed (or +indeed any other state). The questionnaire is an opportunity for the user who +reported the problem to confirm or change this. + +The email contains a unique link to a page on the site, inviting the reporter +to set the state of the problem and, optionally, to add an update. Updates can +include photographs, so sometimes users add a picture to show the repair or +fix. + +The survey link is authorised for the user who submitted the problem report, +because it's been sent directly to the email address they've registered with +your site. This means that the survey is easy for them to access and complete. + +Each survey updates and collects data concerning a _single_ report. It's not +a questionnaire about the general performance of your site. + +## Follow-up surveys + +If the user doesn't confirm that the problem has been fixed, FixMyStreet will +offer to send another survey in another four weeks. That's an opt-in question: +the process will repeat with a new email and survey in four weeks' time, but +only because the user agreed to this. + +## The survey email + +The email that is sent out is made using the `questionnaire.txt` template. The +default is in `/templates/email/default/`. Of course, you should override this +in your own +<a href="{{ "/glossary/#cobrand" | relative_url }}" class="glossary__link">cobrand</a> +— see more about +[customising email templates]({{ "/customising/templates/#emails" | relative_url }}). + +The email message contains a link to the survey page that includes a token that +authenticates the user who submitted the report (this is possible because it is +sent directly to their own email address). + +The basic wording of the email is shown below. We put more information in the +footer (such as links to the site and related social media), and include the +text of the report that was submitted. + + Hello Anne Example, + + 4 weeks ago, you reported a problem using FixMyStreet. + + The details of that report are at the end of this email. + + To keep FixMyStreet up to date and relevant, we'd appreciate it if + you could follow the link below and fill in our short questionnaire + updating the status of your problem: + + https://fixmystreet.example.com/Q/BJ6muiBaxLwuF7kwqo + + All the best, + + The FixMyStreet team + ... + +## What's in the survey? + +The default survey invites the user to make an +<a href="{{ "/glossary/#update" | relative_url }}" class="glossary__link">update</a> +to the problem report: + + * change the <a href="{{ "/glossary/#state" | relative_url }}" class="glossary__link">state</a> + — for example, to _fixed_, because it's been fixed (unless it was + already in that state) + * add a comment or description (optional) + * upload a photo (also optional) + +It also asks: + + * have you ever reported a problem to the body before? + * (if the problem has not been marked as fixed) do you want to receive + another survey email in four weeks' time? + +The default template is defined in `/templates/web/default/questionnaire/*`, +with the questions in `index`. As with all templates, you can override +these with your own cobrand — for details, see +[customising templates]({{ "/customising/templates/#emails" | relative_url }}). + +Note that if you want to collect other data in your survey, you'll need to +update the source code to handle this. + +If the user changes the state of a problem that is currently _fixed_ to +something else, that is, they effectively re-open the problem, then the update +comment is not optional. + +## How to see the results + +You can see the collected results of surveys by logging in as an +<a href="{{ "/glossary/#administrator" | relative_url }}" class="glossary__link">administrator</a> +and visiting `admin/questionnaire` in the admin (or click on **Survey** in the +admin menu bar). + +The survey results are shown as total counts and percentages. They provide the +following numbers: + +### First-timers, or repeat users? + +* _Reported before / Not reported before_ + <br> + How many reports were made by users who had reported a problem before, and + how many are first-time reporters? + +We collect that information because it's a key indicator of how much impact a +platform like FixMyStreet is having. Is it encouraging and enabling people who +had not previously engaged with authorities to do so? + +### How did the state change in the surveys? + +* _Old state_ + <br> + The state the problem was in when the user did the survey (remember that + anyone, including the body or the user themselves, may have set the state + already, before the survey was sent). + +* _New state_ + <br> + What state did they change it to? + +* _Total_ + <br> + This is the number of problem reports (also expressed as a percentage) that + users have moved from the old state to the new state in their surveys. + +How complex these results are will depend to some extent on the states that +your site allows. For example, if you've allowed +<a href="{{ "/glossary/#staff-user" | relative_url }}" class="glossary__link">staff users</a> +to have more detailed states to choose from than the public (such as "fixed +— council", or "in progress"), then you'll have more combinations to +deal with. See the [admin manual]({{ "/running/admin_manual/" | relative_url }}) for more +information about the report states that are available to staff users. + +## How to turn questionnaire-sending off + +By default, your site will send out questionnaires. + +If you don't want your site to send out questionnaires, you need to override +the `send_questionnaires` method in the `Cobrand` module for your cobrand. +Surveys will never be sent if that method returns false. This is not controlled +by a configuration setting, so you do need to edit the Perl code — see +more about [changing the Cobrand module](customising/cobrand-module). + diff --git a/docs/running/users.md b/docs/running/users.md new file mode 100644 index 000000000..87b38f0d2 --- /dev/null +++ b/docs/running/users.md @@ -0,0 +1,165 @@ +--- +layout: page +title: Managing users in FixMyStreet +author: dave +--- + +# Managing users in FixMyStreet + +<p class="lead">Members of the public who just want to report a problem often +don't expect or want to create an account. They choose confirmation-by-email +instead of logging in. Nonetheless FixMyStreet does offer admin capability for +managing your users.</p> + +Regular users or staff can benefit from having an account -- they can set a +password to make future visits to the site easier. But this is not mandatory. + +## How users are normally created + +You do not need to create users before the system goes live. Public user +accounts are created during normal operation. In fact, **it's common to +*never* create a user in the admin** because the FixMyStreet site takes care +of it for you.. + +A new user record is created when an email confirmation link is clicked +(unless, of course, the user already exists with that email address). This +process is automatic and, unless the user subsequently sets a password, most +people don't consider their interaction with FixMyStreet as being +account-based. For example, around 70% of the users who have reported a +problem on the UK's [fixmystreet.com](https://www.fixmystreet.com) site did not +use a password (this effectively means: they did not consider creating an +account). + +## Manually creating a new account (in the admin) + +Sometimes it's helpful to manually create a new account for someone -- +typically this is for a staff user (see below). + +Firstly if you don't have admin access, you'll want to run the +`bin/createsuperuser` script to create a user that has access to the admin. + +You can create a new user account explicitly using the admin. Go to +`admin/users` and fill in the form. A confirmation email is not sent to the +email address if you create a new account in this way. + +## Users' passwords + +If a user sets a password, they can use it to login on future visits (instead +of using a confirmation link in an email). We don't make this mandatory. + +### Setting or changing a password + +Any user can set a password by going to `/auth` and entering a password. A +confirmation link is emailed in the same way as usual. Clicking on the link +sets the password for future use, and also confirms the current session. + +Changing a password is the same as setting it. A confirmation link is sent to +the email, which they must click on before the change is made. There's no need +for the user to enter their *old* password when changing an existing one, +because the authorisation is still sent as an email confirmation link anyway. + +You cannot change a user's password within the admin pages. + +### Storing passwords + +Passwords are hashed (one-way encryption) when they are stored in the +database. You cannot recover a user's password; if they forget it, they must +set a new one. + +## Changing a user's email address + +You can change a user's email address or name by finding their record at +`admin/users` and changing the entry there. Email addresses must be unique. + +## When users misbehave + +Occasionally a user repeatedly posts inappropriate or vexations posts. In our +experience this is much less common than most people expect. However, it's a +problem that arises from time to time. As administrator of your installation, +there are two actions you can take. Firstly, you can *flag* a user, which is +just a way of marking them (in the admin) so you and other administrators know +to keep an eye on them. Secondly, you can add their email address to the +"abuse table". + +### Flagging a user + +Flagging a user has no practical effect, other than to mark the user as one +whose actions need to be checked. You can see the flagged users by going to +`admin/flagged`. + +### Blocking a user's email address + +If a user persistently abuses your installation, by repeatedly creating +inappropriate or false reports, for example, you can ban them. If a user +creates a report while they are banned, they are automatically hidden and not +sent to the bodies (see [how FixMyStreet sends +reports](/customising/send_reports)). + +To add a user to the 'abuse table', go to the admin pages and find any report +they have created. Click on **ban email address**. + +Users are not automatically notified that they have been banned. + +### How you know when a user is misbehaving + +The default behaviour of FixMyStreet is **not** to moderate reports before +they are displayed (although at least one cobrand does support this). Instead, +every report displayed on the FixMyStreet site has a "report abuse" link, so +anyone can notify you if inappropriate content has been posted. You can hide a +report (go to `/admin/reports` to find it, and mark it as hidden) and +optionally flag or ban its creator. On some installations, staff users can +hide reports themselves. Hiding a report usually occurs *after* it's already +been sent to the body responsible (you're simply hiding it from view on the +FixMyStreet website). + +## Staff user accounts (associated with a body) + +You can mark any FixMyStreet user as belonging to a body. This marks them as a +"staff user" for that body. Staff users have extra privileges *which only apply +to problem reports under the jurisdiction of the body to which the use +belongs*. These permissions can be set on a per-user basis. + +To set (or revoke) staff user status, choose **Users** in the admin, and enter +the email or name. (It's also possible to access a user via the reports they +have made). Choose the appropriate body from the **Body** dropdown. Normal +(not staff) users have no body associated. Then you can assign permissions +to that user, depending upon what they require access to. + +For full details of what staff accounts can do, please see the +dedicated [staff user](../staff/) page. + +<a name="sessions"> </a> + +## How FixMyStreet user sessions work + +*The following information about sessions is here in case you need to +understand how it works. For normal operation, you don't need to worry about +it.* + +By default, FixMyStreet uses email confirmation links, text confirmation codes, +or Facebook/Twitter login tokens, to check that the user is a genuine person, +with access to the email address/phone number they have provided. Even if +Facebook/Twitter are used, the site still performs email confirmation. + +So FixMyStreet uses the email address or phone number as the key piece of +information when identifying a user. For email authentication, it sends a +confirmation link -- with a unique token within it -- to the specified email +address when an unidentified user performs a task that requires authentication, +such as submitting a report, or changing their password. For phone +authentication, it sends a confirmation code by text. + +Clicking on a valid email confirmation link, or entering a text confirmation +code, not only confirms the action it was created for (for example, the report +is marked as *confirmed*, or the password is changed), but also starts a user +session. This means that, for the remainder of the session, other such actions +do not trigger further email confirmations. This is an nonintrusive way of +authenticating report submissions without explicitly using usernames, or +accounts, and is a deliberate part of FixMyStreet's design. + +It *is* nonetheless possible to set a password, and log into FixMyStreet using +the email address as the identifier. Regular users, of course, use this +mechanism. When this happens, a user session is created when they log in. + +A **sign out** link is shown on a user's account page once a user session has +begun. Clicking on it ends the session. User sessions are browser sessions: +they automatically expire when the user's browser shuts down. |