docs: add content as first draft for participant and owner pages

docs/src/index.md

@@ -4,22 +4,22 @@ Hackagon is the Swiss Data Science Center's platform for running hackathons.
 
 ## What is a hackathon on Hackagon?
 
-On this platform a hackathon is:
-
-- an **event** that lasts one or several days;
-- **run by** one or several **hackathon owners**;
-- joined by **participants**, whose registrations the owners approve or reject;
-- **public or private**;
-- built around **projects**, which owners add or participants propose, and which
-  the owners approve or reject;
-- worked on in **teams**, which the owners form from the participants'
-  registration answers and their project preferences;
-- handed in as **submissions**: every member of a team can submit, submissions
-  are versioned, and one can be marked as final; other teams can see final
-  submissions;
-- decided by **voting**, which the owners set up in categories: in each category
-  participants either pick one project or spread a budget of points across the
-  projects.
+On this platform:
+
+- A hackathon is an **event** that lasts one or several days.
+- It is **run by** one or several **hackathon owners**.
+- **Participants** join it. The owners approve or reject their registrations.
+- A hackathon is **public or private**.
+- It is built around **projects**. Owners add projects or participants propose
+  them, and the owners approve or reject them.
+- Participants work in **teams**. The owners form the teams from the
+  participants' registration answers and project preferences.
+- Teams hand in **submissions**. Every team member can submit, submissions are
+  versioned, and one can be marked as final. Other teams can see final
+  submissions.
+- **Voting** decides the outcome. The owners set it up in categories. In each
+  category participants either pick one project or spread a budget of points
+  across the projects.
 
 ## Roles
 
@@ -38,11 +38,11 @@ This first version covers hackathon owners and participants.
 
 ## Limitations
 
-- The platform is not a place for data and code to live;
+- The platform is not a place for data and code to live.
   [Renku](https://renkulab.io/) is one such place.
 - The platform does not organize anything on site. To get help organizing a
   hackathon, email us at
-  [hackathon@datascience.ch](mailto:hackathon@datascience.ch); we offer
+  [hackathon@datascience.ch](mailto:hackathon@datascience.ch). We offer
   different packages.
 
 ```{toctree}

docs/src/owner/index.md

@@ -2,8 +2,8 @@
 
 This guide is for hackathon owners: the people who set up and run a hackathon.
 
-The pages under **Manage Hackathon** in a hackathon's menu, in the order they
-appear there:
+The pages under {guilabel}`Manage Hackathon` in a hackathon's menu, in the order
+they appear there:
 
 ```{toctree}
 :maxdepth: 1

docs/src/owner/manage-forms.md

@@ -1,5 +1,38 @@
 # Manage Forms
 
-The questions people answer when they register, and their answers.
+:::{admonition} Owner's Manage Forms
+
+The questions people answer when they register. It shows:
+
+- [Registration form](#registration-form): the questions, in order
+- [A question](#a-question): its type, options and settings
+
+It might also show:
+
+- [Answers](#answers): once someone has answered
+
+:::
 
 ![The Manage Forms page of a hackathon, as its owner sees it](../static/screenshots/manage-forms.png)
+
+## Registration form
+
+- Click {guilabel}`New question` to add a question. Click {guilabel}`Edit` or
+  {guilabel}`Delete` next to a question to change or remove it.
+- Once people have answered, type, options and {guilabel}`Required` are locked,
+  and deleting a question discards its answers.
+
+## A question
+
+- Enter the {guilabel}`Key`, {guilabel}`Question`, {guilabel}`Answer type` and
+  {guilabel}`Position`. Tick {guilabel}`Required` if everyone must answer.
+- Tick {guilabel}`Show answers to participants` to share the answers on
+  [Participants](../participant/member-participants.md).
+- For choice questions, enter the {guilabel}`Options`, one per line.
+
+## Answers
+
+- Click {guilabel}`See the answers` to see, per question, who answered and what.
+- Each person's answers are also on
+  [Manage Participants](manage-participants.md).
+- Answers help you form teams, see [Manage Teams](manage-teams.md).

docs/src/owner/manage-invites.md

@@ -1,6 +1,33 @@
 # Invitations
 
-Only in a private hackathon: the links that let invited people see it and ask to
-join.
+:::{admonition} Owner's Invitations
+
+The links that let people into a private hackathon. Only for private hackathons.
+It shows:
+
+- [Live links](#live-links): links that work, to copy or revoke
+- [New link](#new-link): create another one
+
+It might also show:
+
+- [No longer working](#no-longer-working): revoked and expired links
+
+:::
 
 ![The Invitations page of a hackathon, as its owner sees it](../static/screenshots/manage-invites.png)
+
+## Live links
+
+- Copy a link into an email. Click {guilabel}`Revoke` if it spreads.
+- Someone with a valid link joins straight away, without the waitlist.
+- Links work only while registration is open, see
+  [Settings](manage-settings.md).
+
+## New link
+
+- Enter an optional note on who it is for, then click {guilabel}`Create link`.
+- A link stops working when the hackathon ends.
+
+## No longer working
+
+- Revoked or expired links, for reference.

docs/src/owner/manage-pages.md

@@ -1,6 +1,27 @@
 # Manage Pages
 
-The hackathon's own pages, such as rules or a schedule, which participants find
-in the menu.
+:::{admonition} Owner's Manage Pages
+
+The hackathon's own pages, such as rules or a schedule. It shows:
+
+- [Pages](#pages): every page, in menu order
+- [A page](#a-page): title, visibility and content
+
+:::
 
 ![The Manage Pages page of a hackathon, as its owner sees it](../static/screenshots/manage-pages.png)
+
+## Pages
+
+- Drag or use the arrows to change the order in the menu.
+- Click the eye to show or hide a page for participants.
+- Click {guilabel}`View` to see a page as participants do, or {guilabel}`Edit`
+  to change it.
+
+## A page
+
+- Click {guilabel}`New page`, then enter a {guilabel}`Title` and the
+  {guilabel}`Content` in Markdown. Tick {guilabel}`Visible to participants` to
+  show it.
+- Visible pages appear in every participant's menu.
+- Click {guilabel}`Delete this page` on a page's edit form to remove it.

docs/src/owner/manage-participants.md

@@ -1,5 +1,38 @@
 # Manage Participants
 
-Everyone who registered, and the people waiting for your approval.
+:::{admonition} Owner's Manage Participants
+
+Everyone who registered. It shows:
+
+- [Participants](#participants): the roster, with search and CSV download
+- [A person](#a-person): answers, teams, and what you can change
+
+It might also show:
+
+- [Waitlist](#waitlist): people waiting for your approval
+
+:::
 
 ![The Manage Participants page of a hackathon, as its owner sees it](../static/screenshots/manage-participants.png)
+
+## Participants
+
+- How many there are, who has no email address, who answered the
+  [registration form](manage-forms.md).
+- Click {guilabel}`Download CSV` to get everyone, waitlist included.
+- Click {guilabel}`Manage` to open a [person's details](#a-person)
+
+## Waitlist
+
+- On a public hackathon, everyone who registers waits here.
+- Click {guilabel}`Review` to open a person and approve or decline them.
+- Only owners see the waitlist.
+
+## A person
+
+- All registration answers, including those not shared.
+- Their teams, see [Manage Teams](manage-teams.md).
+- Click {guilabel}`Approve` or {guilabel}`Decline` for someone waiting.
+- Click {guilabel}`Make owner` or {guilabel}`Remove owner` to change their role.
+- Click {guilabel}`Remove from hackathon` to remove them. For an owner, remove
+  the owner role first.

docs/src/owner/manage-projects.md

@@ -1,5 +1,35 @@
 # Manage Projects
 
-Every project, including proposals waiting for your review.
+:::{admonition} Owner's Manage Projects
+
+Every project, whatever its status. It shows:
+
+- [Projects by status](#projects-by-status): approved, awaiting review, rejected
+- [Review](#review): approve or reject a project
+- [New project](#new-project): add one yourself
+
+:::
 
 ![The Manage Projects page of a hackathon, as its owner sees it](../static/screenshots/manage-projects.png)
+
+## Projects by status
+
+- Click the tabs {guilabel}`Approved`, {guilabel}`Awaiting review` and
+  {guilabel}`Rejected` to switch between statuses.
+- Click {guilabel}`Download CSV` to get all projects as a spreadsheet.
+- Click {guilabel}`Review` or {guilabel}`Edit` next to a project.
+
+## Review
+
+- Click {guilabel}`Approve` or {guilabel}`Reject`. When you reject, you can give
+  a reason. {guilabel}`Revoke approval` and {guilabel}`Reconsider` undo a
+  decision.
+- Only approved projects appear on [Projects](../participant/member-projects.md)
+  and on [Manage Teams](manage-teams.md).
+
+## New project
+
+- Click {guilabel}`New Project` to add one. It is the same form participants use
+  to propose.
+- Participants propose only while you allow it, see
+  [Settings](manage-settings.md).

docs/src/owner/manage-public.md

@@ -1,6 +1,26 @@
 # Manage Public Page
 
-The hackathon as everyone outside it sees it: its name, dates, picture and
-description, with a preview beside the fields.
+:::{admonition} Owner's Manage Public Page
+
+The hackathon as everyone outside it sees it. It shows:
+
+- [The form](#the-form): name, visibility, dates, logo and description
+- [The preview](#the-preview): what visitors will see
+
+:::
 
 ![The Manage Public Page page of a hackathon, as its owner sees it](../static/screenshots/manage-public.png)
+
+## The form
+
+- Enter the {guilabel}`Name`, {guilabel}`Starts at`, {guilabel}`Ends at`,
+  {guilabel}`Logo URL` and {guilabel}`Description`. Choose the
+  {guilabel}`Visibility`: public or private.
+- Private hackathons are reached through [Invitations](manage-invites.md).
+- Dates can be changed but not removed once set.
+- Click {guilabel}`Save changes` to save and return to
+  [Settings](manage-settings.md).
+
+## The preview
+
+- Updates as you type.