diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/customising/themes.md | 41 | ||||
| -rw-r--r-- | docs/customising/translation.md | 7 | ||||
| -rw-r--r-- | docs/getting_started.md | 13 | ||||
| -rw-r--r-- | docs/glossary.md | 22 |
4 files changed, 65 insertions, 18 deletions
diff --git a/docs/customising/themes.md b/docs/customising/themes.md index e19004899..a2b498084 100644 --- a/docs/customising/themes.md +++ b/docs/customising/themes.md @@ -298,6 +298,47 @@ for the Kosovan version of Alaveteli, Informata Zyrtare (ignore the file `_custom_state_transitions.html.erb`, which is unused). +## Customising the help pages + +The help pages are a really important part of an Alaveteli site. If you're running Alaveteli in another language, you'll want to show +your users localised versions of the help pages. Even if you're running +the site in English, 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 customise and translate are listed here. We note where Alaveteli links to these pages (sometimes to anchors for particular sections within the pages) or takes users directly to them. + +* [About](https://github.com/mysociety/alaveteli/blob/master/app/views/help/about.html.erb): why the website exists, why it works, etc. When a user starts to make a request in Alaveteli, they are referred to the section here on [why authorities should respond to requests](https://github.com/mysociety/alaveteli/blob/master/app/views/help/about.html.erb#L29). + +* [contact](https://github.com/mysociety/alaveteli/blob/master/app/views/help/contact.html.erb): how to get in touch + +* [credits](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb): who is involved in the site. Importantly, includes [a section](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb#L71) on how users can help the project. Users are referred to this section if they categorise all the requests in the [categorisation game]({{ site.baseurl }}docs/glossary/#categorisation-game). + +* [officers](https://github.com/mysociety/alaveteli/blob/master/app/views/help/officers.html.erb): 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.html.erb): 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. Users are referred to the [section on this page](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.html.erb#L114) about what to do if the authority says they only have a paper copy of the information requested if the user classifies their request as ['gone postal']({{ site.baseurl }}docs/customising/states/#gone_postal). + +* [requesting](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb): 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. Users are referred to the [section on how quickly a response to their request should arrive](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb#L125) when their request is overdue for a response. They are referred to the [section on what to do if the Alaveteli site isn't showing the authority they want to request information](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb#L30) from the page that allows them to list and search authorities. + +* [unhappy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb): 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. In particular users are referred to the [section on using other means](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb#L83) to get their question answered. If the user has requested an internal review of their request, they are referred to [the section on this page](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb#L28) that describes the law relating to how long a review should take. + +* [why email](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_why_they_should_reply_by_email.html.erb): a snippet of information that explains why users should insist on replies by email. This is displayed next to requests that have ["gone postal"]({{ site.baseurl }}docs/customising/states/#gone_postal) - where the authority has asked for the user's physical address so that they can reply with a paper response. + +* [sidebar](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_sidebar.html.erb): a menu for the help pages with a link to each one. You should customise this so that it includes any extra help pages you add, and doesn't include any you remove. + +You can add your own help pages to your site by replacing the default +pages in your theme with your own versions, using a locale suffix for +each page to indicate what language the page is written in. No locale +suffix is needed for pages written for the [default locale]({{ site.baseurl }}docs/customising/config/#default_locale) for the site. +For example, [alavetelitheme contains help +pages](https://github.com/mysociety/alavetelitheme/tree/master/lib/views/help) +for the default 'en' locale and an example Spanish 'about' page. If no +help page exists in the theme for a particular page in the locale that +the site is being viewed in, the default help page in English will be +shown. + + ## Adding new pages in the navigation You can extend the base routes in Alaveteli by modifying diff --git a/docs/customising/translation.md b/docs/customising/translation.md index d4ccedfa7..1a3bc675c 100644 --- a/docs/customising/translation.md +++ b/docs/customising/translation.md @@ -161,6 +161,13 @@ This will be the job of the technical people on your team (or even mySociety's release manager). If translators aren't technical, they can use Transifex without needing to worry about this. +## The help pages + +As the help pages for Alaveteli contain lots of text, they're translated +outside Transifex, by translating each whole help page and replacing it +in the theme that Alaveteli is using, so that it overrides the default +page. See the [guide to Alaveteli's themes]({{ site.baseurl }}docs/customising/themes/#customising-the-help-pages) for more +information on this. ## Developers and internationalisation diff --git a/docs/getting_started.md b/docs/getting_started.md index 30a24a33b..1529046c8 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -216,17 +216,8 @@ often less. But complicated workflows might take a bit longer. 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". +but review their content with a view to your jurisdiction. See [the documentation on Alaveteli's themes]({{ site.baseurl }}docs/customising/themes/#customising-the-help-pages) for details +on which pages are important, and what content they need to have. The help pages contain some HTML. Your tech person should be able to advise on this. diff --git a/docs/glossary.md b/docs/glossary.md index 6b3eedca3..504fb8a05 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -24,6 +24,7 @@ Definitions <li><a href="#bounce-message">bounce message</a></li> <li><a href="#capistrano">Capistrano</a></li> <li><a href="#category">category</a></li> + <li><a href="#categorisation-game">categorisation game</a></li> <li><a href="#censor-rule">censor rule</a></li> <li><a href="#development">development site</a></li> <li><a href="#disclosure-log">disclosure log</a></li> @@ -98,7 +99,7 @@ Definitions <dd> Alaveteli's <strong>advanced search</strong> lets users search using more complex criteria than just words. This includes Boolean operators, - date ranges, and specific indexes such as <code>status:</code>, + date ranges, and specific indexes such as <code>status:</code>, <code>requested_by:</code>, <code>status:</code> and so on. <div class="more-info"> <p>More information:</p> @@ -278,12 +279,19 @@ Definitions Use <a href="#tag" class="glossary__link">tags</a> to associate authorities with specific categories. </p> + More about + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> +</dd> + <dt> + <a name="categorisation-game">categorisation game</a> + </dt> + <dd> + The categorisation game is a way that users of an Alaveteli site can help the site stay current and accurate by updating the status of old requests where the original requester has never said whether the authority responded with the information or not. <div class="more-info"> <p>More information:</p> <ul> <li> - More about - <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> + the categorisation game on the <a href="http://demo.alaveteli.org/categorise/play">demo Alaveteli site</a>. </li> </ul> </div> @@ -485,13 +493,13 @@ Definitions supports. It's sometimes abbreviated as <em>i18n</em> (because there are 18 letters between i and n). <p> - Often you don't need to worry about the details of how this is done + Often you don't need to worry about the details of how this is done because once you've configured your site's <code><a href="{{ site.baseurl }}docs/customising/config/#default_locale">DEFAULT_LOCALE</a></code> Alaveteli takes care of it for you. But when you do need to work on i18n (for example, if you're customising - your site by - <a href="{{ site.baseurl }}docs/customising/translation/">translating</a> it, or + your site by + <a href="{{ site.baseurl }}docs/customising/translation/">translating</a> it, or <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">uploading names</a> of the public bodies in more than one language) at the very least you may need to know the language codes you're site is using. @@ -592,7 +600,7 @@ Definitions to worry about this underlying structure. </li> <li> - See more about the + See more about the <a href="https://www.gnu.org/software/gettext/"><code>gettext</code> system</a>. </li> |