Merge branch 'master' into develop

README.md

@@ -73,6 +73,51 @@ as above; in the other, run
 
     lein figwheel
 
+## Working on this project
+
+You should get the [ZenHub](https://github.com/integrations/zenhub) plug-in for your favourite browser; I use ZenHub for project management, and you (and I) will find collaborating much easier if you do. To join in
+
+1. Clone the project from [my repository](https://github.com/simon-brooke/youyesyet);
+2. Visit the [kanban board](https://github.com/simon-brooke/youyesyet#boards?repos=70809242) and choose an issue you'd like to work on;
+3. Assign that issue to yourself and move it into the 'in progress' column;
+4. Use gitflow: start a new feature;
+5. Work on the issue;
+6. When you are satisfied with your work, commit it to your repository in your feature branch;
+7. Submit a pull request and move the issue to the 'QA/Review' column on the kanban board;
+8. If your work works, I'll integrate it into the develop branch, which you can then pull;
+9. Rinse and repeat!
+
+Obviously I'd appreciate it if you'd [mail me](mailto:simon@journeyman.cc) to introduce yourself, but there's no need to do so.
+
+Finally, if you take a ticket and are not able to finish it, please
+
+1. mail me to say so;
+2. move the issue back to the 'backlog' column on the kanban board.
+
+And *many thanks*!
+
+## More about tooling
+
+Note that all tools recommended in this document are free for non-commercial use; not all are open source.
+
+### Editors/IDEs
+
+I (Simon) use, like and recommend [LightTable](http://lighttable.com/) as my editor; I used to use Emacs, and there is excellent Clojure tooling for Emacs, but these days Emacs ways of working seem just too far from everything else to be comfortable to me. [NightCode](https://sekao.net/nightcode/) is a lighter-weight Clojure IDE which you may like. There's also [Cursive](https://cursive-ide.com/) but it isn't free and I haven't tried it.
+
+### Git
+
+I'm currently using [GitKraken](https://www.gitkraken.com/), on Linux, Windows, and Mac. Like so many things it works best on Linux, but it's good on both other platforms. However, I confess that although I like the ability to easily view the whole structure of the git repository, I tend to drop back to the command line if I'm doing anything tricky with Git.
+
+### Database
+
+The database is [Postgres](https://www.postgresql.org/). I have no plans even to support anything else; I don't feel we have time to mess about. However, if someone wants to fork the code and implement a different database, that's up to them. I'm afraid I do all database stuff from the command line; [there are graphical tools for Postgres](https://wiki.postgresql.org/wiki/Community_Guide_to_PostgreSQL_GUI_Tools) but personally I've never found graphical tools for databases much use.
+
+## Further Reading
+
+If you're thinking of joining in development on this I'd strongly recommend you get hold of a copy of [Dmitry Sotnikov](https://github.com/yogthos)'s [Web Development with Clojure, Second Edition](https://pragprog.com/book/dswdcloj2/web-development-with-clojure-second-edition).
+
+You should also read the [User-Oriented Specification](doc/specification/userspec.md) and any other documentation which appears under the *doc/specification* hierarchy.
+
 ## License
 
 Copyright © 2016 Simon Brooke for the Radical Independence Campaign.

doc/specification/userspec.md

@@ -24,7 +24,7 @@ It's my hope that we'd have enough Issue Experts sitting in the comfort of their
 
 ### Analysts
 
-*Canvassers* are able to see voter canvas for the streets immediately around where they are working. They must be able to do so, because otherwise they cannot effectively canvas. But we must assume that sooner or later a hostile person will join the system as a canvasser, so canvassers should not have access to wider canvas data. Therefore we need a category of trusted user who can view wider maps of where canvas data has been collected, in order to be able to direct teams of canvassers to areas where it has not been collected. For want of a better word I'll call these *Analysts*.
+*Canvassers* are able to see voter canvas data for the streets immediately around where they are working. They must be able to do so, because otherwise they cannot effectively canvas. But we must assume that sooner or later a hostile person will join the system as a canvasser, so canvassers should not have access to wider canvas data. Therefore we need a category of trusted user who can view wider maps of where canvas data has been collected, in order to be able to direct teams of canvassers to areas where it has not been collected. For want of a better word I'll call these *Analysts*.
 
 ### Administrators
 
@@ -88,12 +88,14 @@ The *Electors View* shows a schematic of the registered electors in a dwelling:
 
 ![Electors View](https://raw.githubusercontent.com/simon-brooke/youyesyet/master/dummies/occupants_800.png)
 
-One figure is shown for each elector, labelled with their name. Below the figure are:
+One figure is shown for each elector, labelled with their name. In the dummy pages I've shown gendered stick figures, because I believe that in many casesthis will help the canvasser identify the person who has answered the door; but this may be seen as excluding electors with non-binary gender, and, in any case, I believe we don't actually get gender data (other than salutation) in the electoral roll data. So this may have to be reconsidered.
+
+Below the figure are:
 
 1. One clear 'voting intention' button for each option (e.g., 'Yes', 'No'), greyed unless selected;
 2. One issues button.
 
-Selecting an option icon records that the elector represented by the figure has expressed an opinion that they will vote for that option. Selecting the issues icon brings up and issues view.
+Selecting an option icon records that the elector represented by the figure has expressed an intention that they will vote for that option. Selecting the issues icon brings up and issues view.
 
 ## Issues View