Merge pull request #113 from jonodrew/write-docs

Committing the docs, as discussed

LICENSE

@@ -1,21 +1,10 @@
-MIT License
+# Licence
 
-Copyright (c) 2021 Jonathan Kerr
+Any original code in this repository is released under the [Open Government License v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Any packages this software relies upon are released under their own licences, and you should check their documentation. 
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+## Contributors
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+- [Jonathan Kerr](https://www.twitter.com/jonodrew)
+- [John Peart](https://johnpe.art)

app/main/routes.py

@@ -37,12 +37,12 @@ def index():
 
 @main_bp.route("/cookies")
 def cookies():
-    return render_template("cookies.html", title="Cookies")
+    return redirect("http://docs.mentoring.service.civilservice.lgbt/cookies/")
 
 
 @main_bp.route("/privacy-and-data")
 def privacy():
-    return render_template("privacy-and-data.html", title="Privacy and data")
+    return redirect("http://docs.mentoring.service.civilservice.lgbt/privacy/")
 
 
 @main_bp.route("/upload", methods=["GET", "POST"])

docker-compose.override.yml

@@ -6,3 +6,11 @@ services:
     environment:
       - USERNAME=CSLGBT
       - PASSWORD=HorseBatteryStapleCorrect
+
+  jekyll:
+    build:
+      context: "./docs/"
+    ports:
+      - "4000:4000"
+    volumes:
+      - ./docs:/srv/jekyll

docs/404.html

@@ -0,0 +1,5 @@
+---
+layout: four-oh-four
+permalink: /404.html
+---
+

docs/Dockerfile

@@ -0,0 +1,4 @@
+FROM jekyll/jekyll:latest
+COPY Gemfile /srv/jekyll
+RUN bundle install
+CMD jekyll serve --watch --force_polling --verbose --livereload

docs/Gemfile

@@ -0,0 +1,13 @@
+# Gemfile
+
+source 'https://rubygems.org'
+
+gem 'jekyll', '~> 4.0'
+
+group :jekyll_plugins do
+  gem "jekyll-remote-theme"
+  gem "jekyll-sitemap"
+  gem "jekyll-feed"
+  gem "jekyll-redirect-from"
+end
+gem "webrick", "~> 1.7"

docs/_docs/architecture.md

@@ -0,0 +1,23 @@
+---
+title: System architecture
+excerpt: How everything fits together
+category: Technical detail
+---
+
+## Meet the cast
+There are four key characters in this service. The web server, which responds to requests from users. The queue,
+where the web server puts demands for people to be matched. A worker machine, which picks matching tasks off the
+queue and processes them. Finally, the results store, where the worker machine drops its completed matches.
+
+While the web server waits for the task, it currently just shows a plain screen. This is definitely a bad user
+experience, but I don't yet want to cram more javascript into this system. However, I accept that this probably
+means doing something clever with attachments, encryption, emails, and other such things.
+[Pull requests are welcome.](https://www.github.com/jonodrew/mentor-match)
+
+In the current system, the web server is Flask. The queue and the results store are both played by Redis, and the
+worker is Celery. There is
+[a fork of this system exploring whether this could be done with AWS](https://github.com/mforner13/mentor-match). There is no doubt it
+would be a damn sight more complicated, more difficult to debug, and out of date before long.
+
+Nonetheless, I hope it works, because that is inevitably the way the world is going. And it'll be cheaper to
+actually run.

docs/_docs/contributing.md

@@ -0,0 +1,20 @@
+---
+title: Contributing
+excerpt: "How to contribute to the code base or documentation"
+category: Meta
+---
+
+You can contribute to this project on Github.
+
+[Visit the Github repository](https://github.com/jonodrew/mentor-match)
+
+## Roadmap
+
+The roadmap for this project is published on Github.
+
+[Visit the roadmap on Github](https://github.com/users/jonodrew/projects/1)
+
+## Principal contributors
+
+- [Jonathan Kerr](https://www.twitter.com/jonodrew)
+- [John Peart](https://johnpe.art)

docs/_docs/cookies.md

@@ -0,0 +1,18 @@
+---
+title: Cookies
+excerpt: "This page explains the use of cookies on this website"
+category: Policy
+---
+
+Cookies are small files saved on your phone, tablet or computer when you visit a website.
+
+We use cookies to make the Civil Service LGBT+ mentoring programme Mentor Matcher work.
+
+## Essential cookies
+
+We use some cookies to make the Mentor Matcher work properly. We do not need to ask permission to use them.
+
+| Name | Purpose | Expires |
+|------|---------|---------|
+| `data-folder` |	This unique string is the name of the folder where your uploaded data is stored | 30 minutes |
+| `matching_func` | Stores the choice you make about how mentors and mentees should be matched together | 30 minutes | 

docs/_docs/getting-started.md

@@ -0,0 +1,37 @@
+---
+title: Running locally
+excerpt: "How to deploy this software"
+category: Getting started
+---
+
+This software requires `docker-compose` to run locally. It uses Redis as a backend and queue; Celery to process
+long-running tasks, and Flask to run the web application. Docs are served with Jekyll.
+
+By default, the service can be accessed on the following ports:
+
+| service | port |
+|---------|------|
+| flask   | 5001 |
+| redis   | 6379 |
+| docs    | 4000 |
+
+## Installing dependencies
+
+You **must** install `docker-compose` to use this software. [Follow the documentation from Docker](https://docs.docker.com/desktop/) to install the required software.
+
+After `docker-compose` is installed, clone [the mentor match repository](https://www.github.com/jonodrew/mentor-match). This repository is hosted on Github, but a Github account is not required to clone the repository. 
+
+A Github account is required if you wish to [contribute to the documentation or code](/contribute).
+
+Use the command line to get to where you've cloned this repository. 
+
+From the repository folder, in the command line run:
+
+```
+docker-compose up
+```
+
+You should now be able to access the service on the `localhost:` followed by the ports above. I recommend starting
+with [the docs](localhost:4000), so you can come back here and keep going!
+
+To stop the service at any time, just press the control (<kbd>Ctrl</kbd>) key and <kbd>C</kbd> key together.

docs/_docs/licences.md

@@ -0,0 +1,9 @@
+---
+title: Licences
+excerpt: "Terms for use and reuse of this project"
+category: Meta
+---
+
+Any original code in this repository is released under the [Open Government License v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
+
+Any packages this software relies upon are released under their own licences, and you should check their documentation.

docs/_docs/notifications.md

@@ -0,0 +1,20 @@
+---
+title: Notifying users
+excerpt: How to use the notification service, and add a new one
+category: Technical detail
+---
+## Telling participants about their matches
+
+Having conducted a matching exercise, the next step is to let participants on the programme know that they've been matched. We use [GOV.UK Notify](https://www.gov.uk/notify) to notify participants.
+
+The system allows you
+to download a zipped folder that contains rows of CSV data. This data is in a format that works with templates we have set up in our GOV.UK Notify. You could use another email service that supports templating or mail merging, if you prefer.
+
+The data is deleted from the system once it's been downloaded, or after a period of time. This period can be set in
+seconds using the environment variable `DATA_STORAGE_PERIOD_SECS`. The task is carried out by Celery - see
+`app.tasks.tasks.delete_mailing_lists_after_period`.
+
+## Coming soon
+
+In release 2.5.0, users will be able to rely directly on GOV.UK Notify to notify participants of their matches. Keep an eye
+on our [roadmap](https://github.com/users/jonodrew/projects/1) for more details.

docs/_docs/privacy.md

@@ -0,0 +1,61 @@
+---
+title: Privacy
+excerpt: "This page explains the privacy and data policy for this service"
+category: Policy
+---
+
+The Civil Service LGBT+ Network is a volunteer-led employee network for the UK Civil Service. We follow Civil Service policies and procedures.
+
+The **{{site.title|downcase}}** service is a web service used to match mentees with mentors as part of the Civil Service LGBT+ mentoring programme. This policy explains how we use the data that is uploaded to the service.
+
+## What information is collected and how it is used
+
+The Mentor Matcher service is a tool that volunteers of the Civil Service LGBT+ Network can use to automate the process of matching mentors and mentees who have signed up to the Civil Service LGBT+ Network's mentoring programme.
+
+**You must not use this service without collecting explicit permission from users to process their data.**
+
+Data for the mentor matcher must be uploaded to the service in a specific format. The data must be in two spreadsheets: `mentees.csv` and `mentors.csv`.
+
+The data collected as part of the programme includes, but is not limited to a participant's:
+
+- name
+- email address
+- place of work
+- job title
+- professional or functional anchor
+- grade
+
+People signing up to take part in the mentoring programme must have given explicit consent for their data to be used for the purpose of matching mentors and mentees. **If this consent has not been obtained, you should not use this service to match mentors and mentees.**
+
+To enable the mentor matcher to function, all of the data collected as part of the programme is uploaded to a server and processed. Once mentors and mentees are matched together, users of this service can download the data. The data is deleted once it has been downloaded.
+
+Provided consent was collected in the appropriate manner when participants register for the programme, no further consent is required to use this tool, as it is an essential part of the programme.
+
+Special category data is collected as part of the programme. This service processes special category data in order to make the programme function. Where special category data is collected and processed, explicit consent should be been gained from the data subject. **If this consent has not been obtained, you should not use this service to match mentors and mentees.**
+
+## How the data is protected and how long it is retained for
+
+We implement a variety of security measures to maintain the safety of data used on this service.
+
+The data uploaded to this service is only retained for as long as is strictly necessary and it is regularly erased to mitigate against it being accessed by others.
+
+## How to contact us
+
+Please [contact us](https://www.civilservice.lgbt/contact-us/) if you have any questions about this policy or information we hold about you.
+
+## Changes to this policy
+
+We keep this policy under review. Any updates to this policy will be published on this website. This policy was last updated on 26 August June 2022.
+
+<details markdown=1>
+<summary>Updates to this policy</summary>
+
+### 26 August 2022
+
+This policy was updated to change the way we publicise changes to this policy.
+
+### 25 June 2022
+
+This policy was updated to reflect changes to the Civil Service LGBT+ mentoring programme that allowed participants to provide special category data, and to be matched on that basis.
+
+</details>

docs/index.md

@@ -3,3 +3,12 @@ title: Mentor matcher
 excerpt: This documentation is for the Civil Service LGBT+ mentoring programme mentor matcher software package.
 ---
 
+## About this documentation
+
+This documentation explains how the **{{ site.title | downcase }}** software package works, as part of the Civil Service LGBT+ mentoring programme.
+
+## Contributing
+
+You can contribute to this documentation by raising a pull request on Github. The documentation for this software is located in the `/docs` folder of the repository.
+
+[Visit the Github repository](https://github.com/jonodrew/mentor-match)