Start a glossary

docs/glossary.md

@@ -0,0 +1,39 @@
+# Glossary of OpenTally terminology
+
+Terminology relating to the single transferable vote is varied and not standardised. This page describes how terms are used in OpenTally.
+
+## Candidates
+
+A ***continuing candidate*** is a candidate who has been neither elected nor excluded (nor doomed, when constraints are in use). Other sources sometimes call this a *hopeful* candidate.
+
+A candidate is ***elected*** upon meeting the quota. A candidate is ***excluded*** upon being eliminated from the count.
+
+When constraints are in use, a candidate is ***guarded*** if they must be elected to obtain a result conforming to the constraints, and ***doomed*** if they must not be elected to obtain a result conforming to the constraints.
+
+## Stages
+
+In the single transferable vote, counting proceeds in ***stages***. In OpenTally, the defining feature of a stage is that it is at the end of each stage that candidates are declared elected or excluded. Other sources sometimes call these *rounds* or *counts*.
+
+The first stage of an election count is the distribution of first preferences. Each subsequent stage involves the distribution of an elected candidate's surplus, or the exclusion of a candidate.
+
+According to the particular rules in use, the exclusion of a candidate may take place over multiple stages. Other sources sometimes call these *substages*, but where candidates are declared elected or excluded at the end of each, OpenTally still calls these *stages*.
+
+## Ballots and votes
+
+A ***ballot*** represents a sequence of preferences, and when allocated to a particular candidate, has an associated ***value***. The unit for value is the ***vote***. The initial value associated with a ballot at the distribution of first preferences is the ballot's ***weight***.
+
+A ***parcel*** is a set of ballots allocated to a particular candidate (or exhausted) all at the same value (relative to their weight). Other sources sometimes call this a *bundle* or *batch*.
+
+In OpenTally, value is tracked at the level of parcels rather than individual ballots, so the value of an individual ballot is calculated when required as the ballot's weight multiplied by the value of the parcel containing it.
+
+A candidate's ***progress total*** is the total value of all ballots allocated to that candidate.
+
+## Transferring ballots
+
+The ***next available preference*** on a ballot is the continuing candidate who appears highest on the ballot's preferences. During a surplus distribution or exclusion, a ballot is said to be ***transferable*** if there is a next available preference. If not, the ballot is said to be ***non-transferable*** and set aside as ***exhausted***.
+
+Some sources differentiate between ballots which are *formal* (valid) and *informal* (blank or invalid for some reason or another). OpenTally assumes that all ballots are valid. The number of blank ballots is reported as the number of ballots exhausted in the first stage.
+
+A candidate has a ***surplus*** when their progress total exceeds the quota. During a surplus distribution, the surplus is divided by the number of ballots or votes examined in the distribution (according to the particular rules in use), and the quotient is called the ***surplus fraction***. Other sources, particularly those using the exclusive Gregory or unweighted inclusive Gregory methods, often call this the *transfer value*.
+
+If, as a result of rounding, the number of votes transferred during a surplus distribution is less than the surplus, the difference is called ***loss by fraction***. Other sources sometimes call this *lost fractions*, *vote fractions not transferred due to rounding*, or similar. Some other sources consider the exhausted votes and loss by fraction together, and call the total the *non-transferable difference*, *votes lost*, or similar.

homepage/_layouts/default.html

@@ -26,6 +26,7 @@
 									<li><a class="dropdown-item" href="{{ site.baseurl }}/docs/about.html">About OpenTally</a></li>
 									<li><a class="dropdown-item" href="{{ site.baseurl }}/docs/quick-start.html">Quick start guide</a></li>
 									<li><a class="dropdown-item" href="{{ site.baseurl }}/docs/options.html">Advanced options</a></li>
+									<li><a class="dropdown-item" href="{{ site.baseurl }}/docs/glossary.html">Glossary</a></li>
 								</ul>
 							</li>
 							<li class="nav-item"><a class="nav-link" href="{{ site.git_url }}/tree/">Source Code</a></li>

homepage/_layouts/docs.html

@@ -17,6 +17,7 @@ layout: default
 					<li class="nav-item"><a class="nav-link px-0" href="{{ site.baseurl }}/docs/about.html">About OpenTally</a></li>
 					<li class="nav-item"><a class="nav-link px-0" href="{{ site.baseurl }}/docs/quick-start.html">Quick start guide</a></li>
 					<li class="nav-item"><a class="nav-link px-0" href="{{ site.baseurl }}/docs/options.html">Advanced options</a></li>
+					<li class="nav-item"><a class="nav-link px-0" href="{{ site.baseurl }}/docs/glossary.html">Glossary</a></li>
 				</ul>
 			</div>
 		</div>

homepage/docs/glossary.md

@@ -0,0 +1,6 @@
+---
+layout: docs
+title: "Glossary"
+---
+
+<div class="md-content" markdown="1">{% include_absolute '../docs/glossary.md' %}</div>