Merge pull request #8 from elekto-io/user-docs

Add administration and candidate docs.  Contains a lot of broken link…

Author: jberkus

content/en/docs/Administration/_index.md

@@ -0,0 +1,21 @@
+---
+title: "Administration"
+linkTitle: "Administration"
+weight: 2
+description: >
+  Guide for running elections using Elekto.
+---
+
+Administering elections in Elekto is done through pushes of structured files to a GitHub repository.  See the [configuration guide]({{< ref "/Configuration" >}}) for how to configure the link to the repository.  This guide outlines how the Election Administrators run an individual election.  There are three parts to this:
+
+1. [Creating an election]({{< relref "creating.md" >}})
+2. [Running an election]({{< relref "running.md" >}})
+3. [Concluding an election]({{< relref "concluding.md" >}})
+
+## GitOps and Administration
+
+All Administrative actions happen through a single GitHub repository, or via the Elekto web application.  As such, any references to files or directories in this Guide are references to files and directories under the chosen repository.
+
+For that matter, "administrator actions" in general usually refers to merging files or changes into the designated git repository and branch.  Only two actions take place in the Elekto UI: reviewing voter exceptions and calculating election results.  Everything else happens because an admin changed something in a file and that change was merged.
+
+This means that it is up to your organization to enforce correct permissions and process for the repository and its directories so that administrators can merge what they're supposed to be able to merge (and not what they're not, like someone else's election).  Ideally, your project's CICD workflow will support this.

content/en/docs/Administration/concluding.md

@@ -0,0 +1,37 @@
+---
+title: "Concluding an Election"
+linkTitle: "Concluding"
+weight: 2
+description: >
+  Guide for finishing an election in Elekto.
+---
+
+## Completing the Election
+
+Once the end date for the election is past, it is time for the Election Officers to conclude the election.  This has two steps: computing the candidate rankings, and publishing the election results.
+
+### Computing the Rankings
+
+After the `end_datetime`, Election Officers will be presented with a button on the Administrator Console to compute the election rankings.
+
+![Administrator console with compute winners button]()
+
+Clicking that button does two things.  First, it calculates the preference election mathematical results according to the configured election method, displays those results, and saves them to the database.  Second, if `delete_after` is set, it deletes all of the encrypted links between voters and ballots as an additional privacy measure.
+
+![Administrator console with election results]()
+
+Once the election is calculated, it may not be "re-opened" by extending the end date.
+
+### Publishing the Results
+
+The candidate rankings computed by Elekto are absolute mathematical rankings, and do not take into account organizational rules such as employer, role, or diversity quotas in the elected body. Some organizations also require the election to be certified by another committee. As such, the raw election results are visible only to the Election Officers.
+
+To share the election results with all voters, create a `results.md` file.  This is a simple, markdown-formatted file with no special headers.  You add text in it to share the election results according to the rules of your organization.
+
+![example election results screen]()
+
+### What about Tie Votes?
+
+In a preference election, two candidates with an identical ranking result in a tie.  While Elekto uses special algorithms to prevent tie votes (such as, but default, Schultze), certain combinations of ballots result in an unbreakable tie, particularly in elections with low numbers of ballots.
+
+In the case of a tie, it is up to your election rules to decide how to handle it.  Usually, this means a runoff election.

content/en/docs/Administration/creating.md

@@ -0,0 +1,83 @@
+---
+title: "Creating an Election"
+linkTitle: "Creating"
+weight: 2
+description: >
+  Guide for creating a new election in Elekto.
+---
+
+# The Election Directory
+
+Create a new election in Elekto by creating a directory under the primary elections directory defined in the `ELECTION_DIR` [configuration variable](). What makes it an election directory or not is the presence of an `election.yaml` file; directories without this file will be ignored. This directory may be nested (e.g. `elections/2021/TOC`), but may not be nested under another election directory (one that has an `election.yaml` in it).
+
+Anyone with appropriate permissions on the repository may create an election directory. Usually, creating the directory and file are the first actions of the selected Election Administrators.
+
+Generally, after creating the directory, administrators create an `election.yaml`, `election_desc.md`, and `voters.yaml` file.  
+
+## Election Administrators
+
+Administrators are Elekto users who have special permissions to manage an individual election. Each election must have at least one, and can have any number although practically few elections require more than three. Administrators need not have any control of the underlying infrastructure, nor do they need rights on other elections. They need not even be qualified voters.
+
+How election Administrators are selected is up to the organization running the election and its management of repository change permission.  As far as Elekto is concerned, the people listed in `election.yaml` are the Administrators regardless of how they got there.  Like Voters, Administrators log into Elekto with their OAuth IDs.
+
+## The election.yaml File
+
+This YAML file is the main file that creates and configures an election.  It contains multiple configuration variables, most of which can be changed at multiple times during the election. This file is required for the election to be recognized by Elekto, and if it has errors the election will not appear in the Elekto UI.
+
+See the sample elections in [elekto.meta.test]() for examples of these files.
+
+### election.yaml variables
+
+**name**: Display name of the election. Required, changeable.
+
+**organization**: Group for which this election is being run, for display purposes.  Required, changeable.
+
+**start_datetime**: datetime that voting for the election starts, in UTC time.  At this datetime, the Vote button will be enabled automatically.  Required.  Changeable, but changing it after the election has already started can cause votes to be recorded or discarded improperly.
+
+**end_datetime**: datetime that the election ends, in UTC time. At this time, the Vote button will be disabled automatically. Required.  Changeable until the election ends and a winner has been calculated, after which changes to this field will have no effect.
+
+**no_winners**: number of potential winners in the election, for display to the administrators.  Required, changeable.
+
+**allow_no_opinion**: True/False.  Can voters choose not to rank some candidates?  Required, changeable until the election begins, after which changes to this field may cause votes to be counted incorrectly.
+
+**delete_after**: True/False, whether to delete the encrypted links between voters and ballots once election results are calculated.  Extra voter privacy measure.  Required, changeable until results are calculated.
+
+**show_candidate_fields**: List.  A list of additional display fields for the candidate information pages.  Labels must match the candidate profile fields exactly, or the data will not be displayed.  Optional, changeable at any time.
+
+**election_officers**: List of Oauth IDs of the election officers, determining who they are.  Required, changeable at any time.  Election officers need not be voters.
+
+**eligibility**: Text to display in the "eligibility" section of the UI, for voter information. Optional, changeable at any time.
+
+**exception_description**: Text to display before the Request Exception link. Optional, changeable at any time.
+
+**exceptions_due**: Datetime (in UTC) when exception requests will no longer be accepted, and the Exceptions button will be disabled.  Can be any date before the end of the election. Required, changeable.  If your election does not allow voter exceptions, then set this to the date you create the election.
+
+## The election_desc.md File
+
+This file contains a Markdown-formatted description of the election for voter information purposes.  Since this information is displayed directly above the list of candidates and the voting controls, it's generally a good idea to limit it to about 1/3 page of text.  If you have more election details than that, consider summarizing and linking off to a page on your own website.
+
+This description should include, at a minimum:
+
+* A description of what's being decided in the election
+* Who is hosting the election
+* Contact information for questions
+
+Ideally, it will also include:
+
+* links to voter and candidate eligibility requirements
+* link to candidate nomination process
+* a short version of the election timeline
+
+## The voters.yaml File
+
+The voters file contains a list of Oauth IDs of the qualified voters for the election, as a simple yaml list.  If you wish to create an election before you have pulled the list of voters, then create an empty list until you add the voters.
+
+Voters may be added at any time, until the end of the election.  Voters may also be removed at any time, but if a voter is removed from the file after they have already voted, their ballot will *not* be deleted. As such, if voters need to be removed after an election has begun, it's generally a good idea to abort the election and start a replacement one.
+
+The contents of this file determine whether users see themselves as eligible to vote or not when they log into the UI.  Voters are not otherwise notified when their status changes.
+
+## References
+
+* [Elekto test elections]()
+* [Kubernetes elections]()
+* [Knative elections]()

content/en/docs/Administration/running.md

@@ -0,0 +1,81 @@
+---
+title: "Running an Election"
+linkTitle: "Running"
+weight: 2
+description: >
+  Guide for running an election in Elekto.
+---
+
+An Elekto election includes a pre-election phase and an voting phase.  Depending on your actual election process, the pre-election phase may be unnecessary or handled entirely outside Elekto.  If so, ignore the pre-election phase instructions below.
+
+## A Note on Notifications
+
+Elekto does not send notifications via email or other messaging to anyone.  As such, it is up to your election administrators or officers to send out notifications using your normal community channels.  All community members can check their current status and the status of the election at any time using the web UI,  but they will not receive messages or reminders.  
+
+As such, when this Guide talks about sending reminders or notices, it is talking about action by the Election Officers or other community members.
+
+## Pre-election Phase
+
+Two things happen between the time the election is announced and the time that voting starts.  One is adding voters and acting on exceptions, and the second is adding nominated candidates.
+
+The pre-election phase begins when the election is created in Elekto, and ends when voting starts.
+
+### Managing Voters
+
+Voters are added to an election by populating [the `voters.yaml` file](). Obtaining a list of voters is up to you and your organization, as different groups have vastly different eligibility processes.  Many CNCF projects obtain a list of voters by filing a ticket requesting a data pull from DevStats, CNCF's contributor metrics system.
+
+Once you have obtained a list of qualified voters and added them to `voters.yaml`, you should use your organization's communications channels to announce that voters can [now verify their status](). Voters will be able to log into Elekto and check whether they are Eligible or not via the UI.  If they find they are ineligible, they can request an exception (see below).
+
+Until the election starts, you can freely add and remove voters from `voters.yaml` as your election rules dictate.  We recommend that voters be sorted alphanumerically to make editing the list of voters easier.  Elekto will ignore YAML comments, sort order, and even duplicates in the file. 
+
+#### Voter Exceptions
+
+Organizations may allow people to challenge their voter ineligibility.  Sometimes this is because the voter list process is error-prone, or it can be because some voter criteria are difficult to measure empirically. Based on the Kubernetes project, the term for requesting a ballot when the original voter list did not allow an individual to vote is a "voter exception".
+
+If your voter exception requests are public, then they can be handled via pull requests against the voter list.  However, in Kubernetes and other projects, the exception requests are confidential, in order to spare members from embarrassment if their request is declined.  For this reason, Elekto provides a mechanism for potential voters to request an exception through the UI.
+
+The list of exceptions is available via the Admin screen in the UI.  Access it by clicking the Admin button in the Election Information screen, which should be visible if you are an election officer and logged in.
+
+![photo of admin screen with several exception requests]()
+
+From here you can see the list of requests.  To keep track of which ones you have taken action on, you can click the button to indicate that the requests have been reviewed.  This UI does not add voters whose exception requests are granted, however.  To make voters eligible, you will need to modify the `voters.yaml` file in the repository.  The requests screen is for tracking only.
+
+### Adding Nominated Candidates
+
+Candidates get added to the Elekto system when they have completed and merged profiles.  All profiles will need to be merged before the election begins.  How candidates are nominated and qualified and their profiles are reviewed is entirely up to your organization; Elekto cares only that the candidate.md file has the correct formatting and naming.
+
+To support this, it's usually helpful for the Election Officers to create a `nomination-template.md` file as a template for potential candidates to copy.  EOs are are usually also in charge of helping candidates with completing their profiles and sending out reminders to the community about nomination deadlines.
+
+For more about candidate profiles, see the [Candidate Guide]().
+
+## Voting Phase
+
+At the date and time indicated in the `start_datetime` setting, voters will be able to start voting. No further administrative action is required.  During the voting phase, administrators should have little to do other than adding people to the voters list from the Exceptions.
+
+### The Administrator Console
+
+
+ 
+### Changing the Voters List While Voting
+
+Most organizations continue to accept Voter Exception requests during the voting phase, so that voters can be added and cast ballots even if they are slow to check their status.  Closing exceptions about three days before voting ends can be a good timeline.  
+
+There is no problem adding voters at any time before the `end_datetime` of the election.  Once additional voters are merged into `voters.yaml`, they are immediately able to vote.  
+
+Removing voters from the list, however, is a bad idea once voting has started.  Once a voter has cast a ballot, there is no way to delete their ballot.  While administrators can check whether a particular voter has voted, deleting a voter can be subject to a race condition. That said, problems with duplicate voter IDs (e.g. one voter with two Github accounts) can be cleared up by deleting accounts during voting if you have the active cooperation of the voter.
+
+### Modifying the Election While Voting
+
+Administrators can make changes to `election.yaml` and other settings during the election.  Not all such changes are effective or wise, however.  What follows are some notes on settings it makes sense to change during the voting phase.  Settings that are not mentioned should not be changed. Elekto provides no guardrails here, though; administrators are technically able to change anything they wish.
+
+* `election_desc.md`, `eligibility`, `exception_description`: descriptive fields can be changed any number of times without worry.
+* `end_datetime`: you can change the end time of the election in order to give more time for voting as long as the election has not yet been concluded.
+* `exceptions_due`: you can also extend the Exceptions deadline until the election concludes.
+* `no_winners`, `discard_after`: these fields affect election conclusion, so they can be changed until then.
+* `election_officers`: officers can be added and removed from the election during voting.
+
+You may also make changes and updates to candidate profiles during voting.  However, adding or removing a candidate during voting would make it impossible to correctly compute the ballots.  As such, if you need to change the list of candidates after voting starts, you will need to halt the election and hold a new one.
+
+### Retrieving and Canceling Ballots
+
+During voting, voters may cancel and recast their ballot.  Adminstrators, however, have no mechanism to cancel any voter ballot, or assist voters who have forgotten their passphrase.  This is intentional, in order to prevent Election Officers from manipulating the election.

content/en/docs/Candidates/_index.md

@@ -0,0 +1,46 @@
+---
+title: "Candidate Guide"
+linkTitle: "Candidates"
+weight: 2
+description: >
+  Guide for candidates participating in an Elekto election
+---
+
+## Your Candidate Profile
+
+Your organization will have some type of nomination and confirmation process for how you become a candidate for election.  From Elekto's perspective, though, it's much simpler.  You are a candidate if you have a candidate profile file. The rest of this guide is therefore details on what needs to be in that file.
+
+### Creating a Candidate File
+
+Usually your Election Officers will create a template file for you to copy and create your file.  Your first step is to create a copy of this file with the following naming scheme:
+
+`candidate-youridhere.md`
+
+The filename must start with `candidate-` to be recognized as a candidate file.  The second half of the filename should match the `ID` field inside the candidate file, including case. If the names do not match, then the file will not be recognized as a candidate.
+
+### Contents of the Candidate File
+
+Each candidate file is a markdown file with a small YAML header.  Here's a sample candidate file:
+
+```
+-------------------------------------------------------------
+name: elekto
+ID: elekto
+info:
+- Language: Esperanto
+-------------------------------------------------------------
+
+## Reason for Name
+
+"elekto" is "election" (or selection, or appointment) in the academic language Esperanto.  Also, it sounds like the name of a C-list superhero.
+
+## Availability Search
+
+Nobody currently seems to have trademarks on the name in the USA.  Various domains are available, as is the Github namespace.
+```
+
+The YAML header contains several fields to be filled in by the candidate:
+
+* name: the candidate's name to be displayed in the UI
+* ID: the unique candidate ID.  Usually this is their OauthID, but it can be any arbitrary string as long as it is unique for that election.  It also needs to match the second half of the filename.
+* info: a list of key-value pairs that should match the show_candidate_fields 

content/en/docs/Getting started/installation.md

@@ -57,6 +57,15 @@ Database requirements are very light, so it is completely feasible to run the da
 
 The Elekto database user needs to have permission to create tables. The database must be configured with user/password login.  Other forms of authentication are not yet supported.
 
+Here's an example of doing this on PostgreSQL:
+
+```
+postgres=# create role elekto with login password 'TEST';
+CREATE ROLE
+postgres=# create database elekto owner elekto;
+CREATE DATABASE
+```
+
 The Elekto application will not run if the database is unavailable. The ballot data contained in the database is not stored anywhere else, and as such is unrecoverable if the database is lost. For this reason, it is up to the administrator to set up and manage backups and high availability.  This is particularly a concern for SQLite, which is an embedded database; you will need to set up cron jobs on the server to back this up.
 
 ## Web Server