From b015f34f1fbd9592c5839e5e311136f272df41fa Mon Sep 17 00:00:00 2001 From: Louise Crow Date: Fri, 13 Jun 2014 17:20:46 +0100 Subject: Move docs content under docs/ --- docs/glossary.md | 590 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 590 insertions(+) create mode 100644 docs/glossary.md (limited to 'docs/glossary.md') diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 000000000..8d2f815f9 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,590 @@ +--- +layout: page +title: Glossary +--- + +Glossary +==================== + +

+ Glossary of terms for Alaveteli, mySociety's freedom of information + platform. +

+ +Definitions +----------- + + + + +
+ +
+ Alaveteli +
+
+ Alaveteli is the name of the open source software platform created + by mySociety for submitting, + managing and archiving Freedom of Information requests. +

+ It grew from the successful FOI UK project + WhatDoTheyKnow. + We use the name Alaveteli to distinguish the software + that runs the platform from any specific website that it is powering. +

+
+

More information:

+ +
+
+ +
+ asker agnostic +
+
+ Freedom of Information (FoI) law typically considers + the responses given by the + authorities to be asker agnostic. This means + that the reply should not be any different depending on who asked for the + information. One consequence of this is that the response + can be published, because in theory everyone + could ask for it and expect, by law, to receive the same information. +

+ Despite this, it's still very common all around the world for authorities to reply + to FoI requests privately, instead of publishing their responses themselves. One of the + functions of Alaveteli is, therefore, to act as a public repository of published answers. + This also serves to reduce duplicate requests, by publishing the answer instead of + requiring it to be asked again. +

+
+ +
+ authority +
+
+ An authority is the term we use for any of the bodies, organisations, + departments, or companies to which users can send requests. +
+

More information:

+
    +
  • + An administrator can add, edit, or remove authorities in the admin +
    • +
  • + Authorities are usually, but not always, public bodies that are obliged by the local + Freedom of Information (FoI) law to respond. Sometimes an + Alaveteli site is set up in a jurisdiction that does not yet have FoI law. In the UK, + we add some authorites to our WhaDoTheyKnow + site that are not subject to FoI law, but which have either voluntarily submitted themselves + to it, or which we believe should be accountable in this way. +
    • +
+
+
+ +
+ black hole +
+
+ A black hole is an email address that accepts and destroys + any email messages that are sent to it. Alaveteli uses this for "do not + reply" emails, which are usually automatically generated system emails. +

+
+

More information:

+
    +
  • + Use the config setting + BLACKHOLE_PREFIX + to specify what this email address looks like. +
    • +
  • + Conversely, see + CONTACT_EMAIL + to specify the email address to which users' emails (such as support + enquiries) will be delivered. +
    • +
+
+
+ +
+ Capistrano +
+
+ Capistrano is a remote server automation and deployment tool written in Ruby. + Alaveteli's deployment mechanism, which is optional, uses it. +
+

More information:

+ +
+
+ +
+ censor rule +
+
+ Alaveteli administrators can define censor rules to define + which parts of replies or responses should be + redacted. +

+
+

More information:

+
    +
  • + see the + admin manual + for more about censor rules +
    • +
  • + censor rules may simply redact text that exactly matches a + particular sentence or phrase, or may use + regular expressions +
    • +
+
+
+ +
+ development site (also: dev, development server) +
+
+ A dev server is one that is running your Alaveteli site + so you can customise it, experiment + with different settings, and test that it does what you expect. + This is different from a + production server, which is the one your + users actually visit running with live data, or a + staging server, + which is used for testing code before it goes live. +

+ On your dev server, you should set + STAGING_SITE + to 1. +

+
+ +
+ Freedom of Information (also FOI) +
+
+ Freedom of information laws allow access by the general public + to data held by national governments. They establish a "right-to-know" + legal process by which requests may be made for government-held + information, to be received freely or at minimal cost, barring standard + exceptions. +
+ [from wikipedia] +
+

More information:

+ +
+
+ +
+ git (also github, git repository, and git repo) +
+
+ We use a popular source code control system called git. This + helps us track changes to the code, and also makes it easy for other people + to duplicate and even contribute to our software. +

+ The website github.com is a central, public + place where we make our software available. Because it's Open Source, you can + inspect the code there (Alaveteli is mostly written in the programming language + Ruby), report bugs, suggest features and many other useful things. +

+

+ The entire set of files that form the Alaveteli platform is called the + git repository or repo. When you + install Alaveteli, you are effectively cloning our repository on your + own machine. +

+
+

More information:

+ +
+
+ +
+ holding pen +
+
+ The holding pen is the conceptual place where responses that + could not be delivered are held. They need attention from a administrator. +
+

More information:

+
    +
  • + see the admin manual for + information on dealing with emails in the holding pen +
    • +
+
+
+ +
+ MTA (Mail Transfer Agent) +
+
+ A Mail Tranfer Agent is the the program which actually sends + and receives email. Alaveteli sends email on behalf of its users, and processes + the responses and replies it receives. + All this email goes through the MTA, which is a seperate service on your system. +
+

More information:

+
    +
  • + see these instructions for configuring your MTA + (examples are for exim4 and postfix, two of the most common) +
    • +
+
+
+ +
+ production site (also: live, production server) +
+
+ A production server is one that is running your Alaveteli site + for real users, with live data. This is different from a + development server, which you use make your + customisation and environment changes and try to get them to all work OK, or a + staging server, which is used for testing code + and configuration after it's been finished but before it goes live. +

+ Your production site should be configured to run as efficiently as possible: for + example, caching is enabled, and debugging switched off. + Rails has a "production mode" which does + this for you: set + STAGING_SITE + to 0. Note that if you change this setting after you've + deployed, the rails_env.rb file that enables Rails's production + mode won't be created until you run rails-post-deploy. +

+ If you have a staging server, the system environment of your staging and + production servers should be identical. +

+

+ You should never need to edit code directly on your production server. + We strongly recommend you use Alaveteli's + deployment mechanism + (using Capistrano) to make changes to your production site. +

+
+ +
+ publish +
+
+ Alaveteli works by publishing the + responses it recieves to the + Freedom of Information + requests that its users send. + It does this by processing the emails it receives and presenting them + as pages — one per request — on the website. This makes it + easy for people to find, read, link to, and share the request and the + information provided in response. +
+ +
+ response +
+
+ A response is the email sent by an + authority in reply to + a user's requests. +
+ +
+ recaptcha +
+
+ Recaptcha is a mechanism that deters non-human users, + such as automated bots, from submitting requests automatically. + It requires the (human) user to identify a pattern of letters presented + in an image, which is difficult or impossible for a non-human to + do. Alaveteli uses this to prevent incoming spam. +
+

More information:

+ +
+
+ +
+ redacting (also: redaction) +
+
+ Redacting means removing or hiding part of a message so it + cannot be read: you are effectively removing part of a document from + your site. +

+ This may be necessary for a variety of reasons. For example, a user may + accidentally put personal information into their request, or an + authority may include it in their response. You may also need to + redact parts of requests or responses that are libellous or legally + sensitive. +

+
+

More information:

+
    +
  • + see the + admin manual + for more about how and when you may need to redact information +
    • +
  • + you can do text-only redaction with Alaveteli's + censor rules +
    • +
  • + some things are easier to redact than others — especially in PDFs, + things like signatures or images can be difficult to partially remove. + In such cases, you may need to remove the document entirely. +
    • +
+
+
+ +
+ regular expression (also: regexp) +
+
+ A regular expression is a concise way to describe a + pattern or sequence of characters, letters or words. As an administrator, + you may find regular expressions useful if you need to define censor rules. For example, instead + of redacting just one specific + phrase, you can describe a whole range of similar phrases with one + single regular expression. +

+ Regular expressions can be complicated, but also powerful. If you're not + familiar with using them, it's easy to make mistakes. Be careful! +

+
+

More information:

+
    +
  • + for example, the regular expression + Jo(e|ey|seph)\s+Blogg?s would match names + including + "Joe Bloggs", "Joey Bloggs" and + "Joseph Blogs", but not + "John Bloggs". +
    • +
  • + see Regular + Expressions on wikibooks for more information +
    • +
+
+ +
+ request +
+
+ In Alaveteli, a request is the + Freedom of Information request + that a user enters, and which the site then emails to the relevant + authority. + Alaveteli automatically publishes + the responses + to all the requests it sends. +
+ +
+ Ruby on Rails (also Rails) +
+
+ Alaveteli is written in the Ruby programming language, using + the web application framework "Ruby on Rails". +
+

More information:

+ +
+
+ +
+ Sass (for generating CSS) +
+
+ Alaveteli's cascading stylesheets (CSS) control how the pages appear, and + are defined using Sass. It's technically a CSS extension + language, and we use it because it's easier to manage than writing CSS + directly (for example, Sass lets you easily make a single change that will + be applied to many elements across the whole site). + Rails notices if you change any of + the Sass files, and automatically re-generates the CSS files that the + website uses. +
+

More information:

+ +
+
+ +
+ staging server (also: staging site) +
+
+ A staging server is one that you use for testing code or configuration + before it goes live. This is different from a development server, on which you change the code and settings to + make everything work, or the + production server, which is the + site your users visit running with live data. +

+ On your staging server, you should set + STAGING_SITE + to 1. +

+

+ If you have a staging server, the system environment of your staging and + production servers should be identical. +

+

+ You should never need to edit code directly on your production or staging servers. + We strongly recommend you use Alaveteli's + deployment mechanism + (using Capistrano) to make changes to these sites. +

+
+ +
+ state +
+
+ Each request passes through different + states as it progresses through the system. + States help Alaveteli administrators, as well as the public, + understand the current situation with any request and what + action, if any, is required. +

+ The states available can be customised within + your site's theme. +

+
+

More information:

+ +
+
+ +
+ theme +
+
+ A theme is the collection of changes to the templates + and the code that causes the site to look or behave differently from the + default. Typically you'll need a theme to make Alaveteli show your own + brand. +
+

More information:

+ +
+
+ +
-- cgit v1.2.3