diff options
Diffstat (limited to 'docs/getting_started.md')
| -rw-r--r-- | docs/getting_started.md | 380 |
1 files changed, 380 insertions, 0 deletions
diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 000000000..4bfd9eb24 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,380 @@ +--- +layout: page +title: Getting started +--- + +# Getting started with Alaveteli + +<p class="lead"> + This guide is aimed at people who are thinking about setting up their own + Alaveteli website in a new jurisdiction. +</p> + +For inspiration, take a look at some of the existing Alaveteli websites, like +[tuderechoasaber.es](http://tuderechoasaber.es) (Spain), +[AskTheEU](http://asktheeu.org) (EU), or +[WhatDoTheyKnow](http://www.whatdotheyknow.com) (UK). These sites all use the +Alaveteli software, plus their own custom themes installed on top to make them +look different. + +You don't even need to make a custom theme to get started. You can have a +website that looks like [the demo website](http://demo.alaveteli.org) and +simply drop in your own logo. + +The process of getting your own Alaveteli website up and running could take +anywhere from one day to three months, depending on the scale of your ambition +for customising the software, your access to technical skills, and your +available time. + +You can get a feeling for how things might turn out by reading [how an +Alaveteli was set up in +Spain](http://www.alaveteli.org/2012/04/a-right-to-know-site-for-spain/) +(remember that this was with an experienced developer in charge). You will also +need to think about how you will run the website; a successful Alaveteli +requires lots of ongoing effort to moderate and publicise (see Step 6 and Step +7, below). + +Here are the steps we suggest you follow in order to get started. + +* [Step zero: assemble your initial team](#step-0) +* [Step one: get a working, uncustomised version running](#step-1) +* [Step two: start to gather data about public authorities](#step-2) +* [Step three: customise the site](#step-3) +* [Step four: translate everything](#step-4) +* [Step five: Test drive the site](#step-5) +* [Step six: Market the website](#step-6) +* [Step seven: Maintain the website](#step-7) + + +<a name="step-0"> </a> + +## Step zero: assemble your initial team + +You're unlikely to be able to get much done on your own. You will need +translators, people to hunt down email addresses of authorities, possibly a +designer, and preferably a technical expert to help with customisations. Read +through this guide first, and think about the skills you will need to +successfully launch and maintain the website. + +It took about [ten people (including translators) working for three +days](http://groups.google.com/group/alaveteli-dev/msg/1bd4afd3091f8b4f) to +launch [Queremos Saber](http://queremossaber.org.br/), a Brazilian version of +Alaveteli. + +> It was really cool setting the site up. And even with some minor +> difficulties (most related to the fact that we had no one really experienced +> with both Ruby on Rails and Postfix) it was pretty quick and in less than a +> week we had a fully featured website! +> +> -- _Pedro Markun, Queremos Saber_ + +[AskTheEU](http://asktheeu.org), a much more complete and polished version with +a custom theme and several other customisations, took a team of 2 or 3 people +about 3 months (part time) to complete. + +Ask members of your team to consider joining one of the mailing lists. If you +have any questions, these are the first places to ask. +[alaveteli-users](http://groups.google.com/group/alaveteli-users) is a mailing +list for non-technical users of the software. Post messages there to ask for +advice about getting your project started, questions about how people use the +software, and so on. +[alaveteli-dev](http://groups.google.com/group/alaveteli-dev) is the place to +ask questions of a technical nature, such as problems installing Alaveteli. + +<a name="step-1"> </a> + +## Step one: get a working, uncustomised version running + +You have two options here: install your own copy, or ask the Alaveteli team to +provide a hosted version. + +If you install your own copy, you have complete control over the website, its +performance, how often it is upgraded, and so on. We recommend this as the best +approach. However, you will need some resources to do this. + +Alternatively, we have very limited capacity to run a handful of Alaveteli +sites for willing volunteers. We want to learn more about how we can support +third parties, and to do so we're happy to help host low-volume sites for two +or three partners. However, you will have no service level agreement, no +warranties, and no guarantee on our time: if the website goes down when we're +on holiday, you'll have to wait until we're back! If you want to try this +route, please [get in touch](http://alaveteli.org/contact-us) to find out if +we have capacity. + +### Install your own copy + +You'll need to find a tech person who knows about hosting websites using Apache +and Linux. They don't need to know Ruby on Rails, but it would be a huge +advantage if they do. + +You'll also need to source a server. You should ask your tech person to help +with this. The minimum spec for running a low traffic website is 512MB RAM and +a 20GB disk. 2GB RAM would be ideal. We recommend Debian Squeeze as the +operating system, though any sort of Linux should do. Rackspace offer suitable +cloud servers, which start out at around $25 / month. Then your tech person +should follow the [installation documentation]({{ site.baseurl }}docs/installing). + +Alternatively, you could use Amazon Web Services. This has the +added advantage that you can use our preconfigured [Alaveteli EC2 +AMI]({{ site.baseurl }}docs/installing/ami) to get you +started almost instantly. However, it's more expensive than Rackspace, +especially if you want more RAM. + +### Play around with it + +You'll need to understand how the website works. Until your own copy is +available, you can try the copy running on the [demo +server](http://demo.alaveteli.org) (though note this isn't guaranteed to be +available or working). + +Right now we don't have a guide book, so you'll just have to explore on your +own. + +When you have your own version running, try logging into the admin interface by +adding `/admin` onto the end of your domain name. This will take you to the +administrative interface. It's plain and simple, but functional. For example, +try adding new authorities there, perhaps with your own email address, so you +can see what requests look like to them. + +When trying things out, you need to wear several hats -- as a site +administrator, an ordinary site user, and as a public authority. This can get +confusing with several email addresses, so one quick and easy way to manage +this is to use a throwaway email service like http://mailinator.com. + +<a name="step-2"> </a> + +## Step two: start to gather data about public authorities + +One of the most important things you need to do before launching is to gather +together a list of all the bodies to whom you want to address FOI requests. + +It's a good idea to make a shared speadsheet that you can ask your supporters +to help fill out. A template like [this Google +spreadsheet](https://docs.google.com/spreadsheet/ccc?key=0AgIAm6PdQexvdDJKdzlNdXEtdjBETi1SLVhoUy1QM3c&hl=en_US) is ideal. + +If you email possible supporters asking for help, in addition to helping make +your job easier, it will also help you identify eager people who might be +interested in helping you maintain and run the website. We have written [a +blog post about +this](http://www.alaveteli.org/2011/07/you-need-volunteers-to-make-your-website-work/). + +The admin interface includes a page where you can upload a CSV file (that's a +file containing comma-separated values) to create or edit authorities. CSV is a +convenient format -- for example, it's easy to save data from a spreadsheet as +a CSV file. + +<a name="step-3"> </a> + +## Step three: customise the site + +### Name and social media + +Obviously, you'll want to put your own visual stamp on the site. Once you have +a name for your project (e.g., WhatDoTheyKnow in the UK, AskTheEU in the EU, +InformateZyrtare in Kosovo), register a twitter username, and a domain name. +Alaveteli relies on you keeping a blog for its "News" section, so you might +want to consider setting up a free blog at http://wordpress.com or +http://blogger.com and announce your project with a new blog post. + +### Branding and theming + +Next, think about the visual identity. At a minimum, you should probably +replace the default Alaveteli logo that you can see at the top left of +<http://demo.alaveteli.org>. It's also easy to change the colour scheme. + +If you have a bit more budget and time, you can rework the design more, with a +custom homepage, different fonts, etc; however, the more you customise the +site, the harder it is to upgrade in the future; and you'll need a developer +and/or designer to help do these customisations. We call the custom set of +colours, fonts, logos etc a "theme"; there are some notes for developers about +[writing a theme]({{ site.baseurl }}docs/customising/themes/). You +might spend anywhere between 1 and 15 days on this. + +### Legislative differences + +We rely on users to help categorise their own requests (e.g., as "successful", +or "refused"). We call these categories "states". Most FOI laws around the +world are sufficiently similar that you can probably use Alaveteli's states +exactly as they come out of the box. + +In addition, we have found that it's generally a bad idea to try to implement +laws exactly in the user interface. They are often complicated, and confusing +for users. Since the concept of Alaveteli is to make it easy to exercise the +right to know, we take the view that it's best to implement how a FOI process +*should* be, rather than how it *actually is right now*. + +However, if you really feel you need to alter the states that a request can go +through, it is possible to do this to some degree within your theme. Have a +think about what is required, and then send a message to the Alaveteli mailing +list for feedback and discussion. Then you'll need to ask your developer to +implement the new states. It's usually no more than a couple of days' work, +often less. But complicated workflows might take a bit longer. + +### Write the help pages + +The default help pages in Alaveteli are taken from WhatDoTheyKnow, and are +therefore relevant only to the UK. You should take these pages as inspiration, +but review their content with a view to your jurisdiction. The important pages +to translate are: + +* [About](https://github.com/mysociety/alaveteli/blob/master/app/views/help/about.rhtml): why the website exists, why it works, etc +* [contact](https://github.com/mysociety/alaveteli/blob/master/app/views/help/contact.rhtml): how to get in touch +* [credits](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.rhtml): who is involved in the site. Importantly, includes a section on how users can help the project. +* [officers](https://github.com/mysociety/alaveteli/blob/master/app/views/help/officers.rhtml): information for the officers who deal with FOI at authorities. They get a link to this page in emails that the site sends them. +* [privacy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.rhtml): privacy policy, plus information making it clear that requests are going to appear on the internet. Let users know if they are allowed to use pseudonyms in your jurisdiction. +* [requesting](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.rhtml): the main help page about making requests. How it works, how to decide who to write to, what they can expect in terms of responses, how to make appeals, etc. +* [unhappy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.rhtml): users are taken to this page after a request that has been somehow unsuccessful (e.g. the request has been refused, or the authority is insisting on a postal request). The page should encourage them to keep going, e.g. by starting a new request or addressing it to a different body. +* [why email](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_why_they_should_reply_by_email.rhtml): a snippet of information that explains why users should insist on replies by email. This is displayed next to requests that have "gone postal". + +The help pages contain some HTML. Your tech person should be able to advise on +this. + +Once the pages are written, ask your tech person to add them to your theme. + +Now is also a good time to start thinking about some of your standard emails +that you'll be sending out in response to common user queries and +administrative tasks -- for example, an email that you send to IT departments +asking them to whitelist emails from your Alaveteli website (if your emails are +being marked as spam). See the +[Administrator's Manual]({{ site.baseurl }}docs/running/admin_manual/) for details +on some of the common administrative tasks. There is a list of the +standard emails used by WhatDoTheyKnow on the +[FOI Wiki](http://foiwiki.com/foiwiki/index.php/Common_WhatDoTheyKnow_support_responses). + +### Other software customisations + +Perhaps you would like a new usability-related feature not in Alaveteli +already, like the automated language detection for multi-language websites; or +Facebook integration; or an iPhone app. + +Perhaps you've found an area relating to translations that Alaveteli doesn't +yet support fully (for example, we've not yet needed to implement a site with a +language written right-to-left). + +Perhaps your jurisdiction *requires* a new feature not in Alaveteli -- for +example, users may need to send extra information with their requests. + +In these cases, you will need to get your tech person (or some other software +developer) to make these changes for you. This can be time consuming; new +software development, testing, and deployment is often complex. You should get +expert advice on the amount of extra time this will require. Typically, changes +like these could add between one and three months onto the project schedule. + +<a name="step-4"> </a> + +## Step four: translate everything + +This is potentially a big job! + +If you need to support multiple languages in your jurisdiction, you will need +to translate: + +* public authority names, notes, etc +* public authority bodies +* help pages +* all of the web interface instructions in the software + +It's a bit easier if you only need to support one language in your +jurisdiction: because you'll already have written the help and public authority +information, you'll only need to translate the web interface. + +Public authority names can be edited via the admin interface, or by uploading a +spreadsheet. The help pages need to have one copy saved for each language; your +tech person will put them in the right place. + +The web interface translations are managed and collaborated via a website +called Transifex. This website allows teams of translators to collaborate in +one place, using a fairly easy interface. + +The Alaveteli page on Transifex is at +<https://www.transifex.com/projects/p/alaveteli/>; the translations all live in a +single translation file called +[`app.pot`](https://www.transifex.com/projects/p/alaveteli/resource/apppot/). + +You can set up your language and provide translations there; you can also use +specialise software on your own computer (see the help pages on Transifex) + +There are (at the time of writing) around 1000 different sentences or fragments +of sentences (collectively known as "strings") to be translated. The meaning of +many strings should be fairly obvious, but others less so. Until we write a +guide for translators, the best route to take is translate everything you can, +and then ask your tech person or the project mailing list for advice on +anything you're unsure about. + +Over time, as bugs are fixed and new features are added, new strings are added +to the file. Therefore, you need to keep an eye on `app.pot` and periodically +review the untranslated strings. + +<a name="step-5"> </a> + +## Step five: Test drive the site + +For launch, the tech person should review the [Production Server Best +Practices]({{ site.baseurl }}docs/running/server). + +A low-key launch, where you tell just a few trusted people about the site, is a +very good idea. You can then track how things work, and gauge the responses of +authorities. Responses are likely to vary widely between and within +jurisdictions, and the right way of making your website a success will vary +with these responses. + +<a name="step-6"> </a> + +## Step six: Market the website + +In general, the best way to engage authorities is with a mixture of +encouragement and exposure. In private, you can explain that in addition to +helping them meet their legal requirements and civic obligations, you may be +reducing their workload by preventing repeat requests. In public, you can work +with journalists to praise authorities that are doing a good job, and highlight +ones that refuse to take part. It is, therefore, very important to make links +with journalists with an interest in freedom of information. + +The other important marketing tool is [Google +Grants](http://www.google.com/grants/), a scheme run by Google that gives free +AdWords to charities in lots of countries around the world. You'll find these +an incredibly useful resource for driving traffic to your site. It's well worth +setting yourself up as a charity if only to take advantage of this programme. + +<a name="step-7"> </a> + +## Step seven: Maintain the website + +Running a successful Alaveteli website requires some regular, ongoing input. +This will be easier to do with a small team of people sharing jobs. Hopefully +you have been lucky enough to get funding to pay people to do these tasks. +However, you are also likely to have to rely on volunteers. We've written [a +blog post about the importance of +volunteers](http://www.alaveteli.org/2011/07/you-need-volunteers-to-make-your-we +bsite-work/), which you should read. + +You'll need to set up a group email address for all the people who will manage +the website. All site user queries will go here, as will automatic +notifications from Alaveteli. A group address is really useful for helping +coordinate responses, discuss policy, etc. + +You could get by with just one or two hours per week. This means keeping an eye +on the "holding pen" of the website, where incoming messages that the site +doesn't know how to handle are stored (things like spam, misaddressed messages, +etc). However, the more effort you put into this, the more successful your +website is. To ensure its success, you should be doing things like: + +* Responding to user help enquiries by email +* Monitoring new requests, looking for people who might need help, posting + encouraging comments on their requests +* Monitoring responses from authorities, looking for ones who are trying to + refuse to answer, offering advice to the person who made the request, possibly coming up with publicity to "shame" the authority into answering +* Tweeting about interesting requests and responses +* Writing blog posts about the progress of the project +* Communicating with journalists about potentially interesting stories +* Recruiting volunteers to help with the site +* Categorising uncategorised requests + +See also the [Administrator's Manual](/docs/running/admin_manual), which describes +some of the typical tasks you'll need to perform when your site is up and +running. + +### What else? + +If there's anything you think would be really useful to have in this getting +started guide which is currently missing, let us know so we can add it. |