docs: describe polls, using a markdown file

openapi/components/schemas/poll.md

@@ -0,0 +1,2 @@
+A `Poll` is the core model of the application.
+A `Poll` exposes a list of `Proposal`s, and `Participant`s may individually give each `Proposal` a `Grade`. (in a `Ballot`)

openapi/components/schemas/poll.yaml

@@ -1,5 +1,6 @@
 type: object
-
+description:
+  $ref: 'poll.md'
 properties:
   id:
     type: string
@@ -30,7 +31,9 @@ properties:
       so you should consider the proposals carefully and with gumption.
   proposals:
     type: array
-    description: The proposals being voted in a poll.
+    description: >
+      The proposals being judged by the participants in a poll.
+      It makes no sense to have less than two proposals in a poll.
     minItems: 2
     maxItems: 20
     items: