aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRunasSudo <runassudo@yingtongli.me>2021-10-28 16:28:53 +1100
committerRunasSudo <runassudo@yingtongli.me>2021-10-28 16:28:53 +1100
commit5a652cb46638ba42a0eb31a0295873c192bd8a11 (patch)
tree7f9e02d6899937ce8d8efd313d6bf5312ef1e4ab
parent116d4c385c6f9ba270876bca5fe90c1cb8a01f31 (diff)
Improve online documentation
Diffstat
-rw-r--r--README.md6
-rw-r--r--docs/quick-start.md19
-rw-r--r--homepage/_config.yml3
-rw-r--r--homepage/_layouts/default.html7
-rw-r--r--homepage/_layouts/docs.html37
-rw-r--r--homepage/_layouts/post.html17
-rw-r--r--homepage/assets/docs/005.pngbin0 -> 10833 bytes
-rw-r--r--homepage/assets/docs/010.pngbin0 -> 223851 bytes
-rw-r--r--homepage/docs/about.md (renamed from homepage/about.md)8
-rw-r--r--homepage/docs/options.md15
-rw-r--r--homepage/docs/quick-start.md6
-rw-r--r--homepage/index.html7
12 files changed, 92 insertions, 33 deletions
diff --git a/README.md b/README.md
index 09d7ee2..7f9fb16 100644
--- a/README.md
+++ b/README.md
@@ -28,11 +28,7 @@ OpenTally is highly customisable, including options for:
## Online usage
-After preparing the [BLT file](https://yingtongli.me/git/OpenTally/about/docs/blt.md), open the web UI. Select the BLT file, and click *Count*. OpenTally will count the election and display the results in a count sheet.
-
-By clicking *Show advanced options*, you can customise the options used for the count. A detailed explanation of the various options can be found [here](/opentally/docs/options.html).
-
-Once the count is complete, you can click *Print result* to generate a printable result report.
+See the [quick start guide](/opentally/docs/quick-start.html) for how to use OpenTally online.
## Command line usage
diff --git a/docs/quick-start.md b/docs/quick-start.md
new file mode 100644
index 0000000..03ee796
--- /dev/null
+++ b/docs/quick-start.md
@@ -0,0 +1,19 @@
+# Quick start guide
+
+Prepare a [BLT file](https://yingtongli.me/git/OpenTally/about/docs/blt.md) containing the ballot papers in the election. If you would just like to see a demonstration election, you can download a sample BLT file <a href="https://yingtongli.me/git/OpenTally/plain/tests/data/prsa1.blt" target="_blank">here</a>.
+
+Launch OpenTally at <a href="/opentally/stv/" target="_blank">https://yingtongli.me/opentally/stv/</a>.
+
+In the top-right corner of the page, click *Browse* and select the BLT file you prepared or downloaded:
+
+![Browse button](/opentally/assets/docs/005.png){: style="max-height:45px;display:block;margin:0 auto" }
+
+Click the *Count* button to generate the result sheet for the election:
+
+![Result sheet](/opentally/assets/docs/010.png){: style="max-height:500px;display:block;margin:0 auto" }
+
+<!-- For more details on how to interpret the result sheet, see TODO. -->
+
+To change the STV rules used to count the election, click the *Preset* dropdown at the top of the page, and choose a preset. Alternatively, click *Show advanced options*. A detailed explanation of the various presets and options can be found [here](/opentally/docs/options.html).
+
+Once the count is complete, you can click *Print result* to generate a printable result report or PDF. To ensure the result report displays correctly, check that the paper size in the print window matches the paper size selected in OpenTally, the print orientation is set to landscape, and the scale is set to 100%.
diff --git a/homepage/_config.yml b/homepage/_config.yml
index c53c7cf..3d9d399 100644
--- a/homepage/_config.yml
+++ b/homepage/_config.yml
@@ -26,3 +26,6 @@ kramdown:
# - vendor/cache/
# - vendor/gems/
# - vendor/ruby/
+
+keep_files:
+ - stv
diff --git a/homepage/_layouts/default.html b/homepage/_layouts/default.html
index 1b10045..19a5408 100644
--- a/homepage/_layouts/default.html
+++ b/homepage/_layouts/default.html
@@ -6,7 +6,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
- <title>{% if post.title %}{{ post.title }}{% else %}{{ site.title }}{% endif %}</title>
+ <title>{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}</title>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.5.0/font/bootstrap-icons.css" integrity="sha256-PDJQdTN7dolQWDASIoBVrjkuOEaI137FI15sqI3Oxu8=" crossorigin="anonymous">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
</head>
@@ -23,8 +23,9 @@
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" id="navbarDropdownBlog" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a>
<ul class="dropdown-menu dropdown-menu-end" aria-labelledby="navbarDropdownBlog">
- <li><a class="dropdown-item" href="{{ site.baseurl }}/about.html">About OpenTally</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/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>
</ul>
</li>
<li class="nav-item"><a class="nav-link" href="{{ site.git_url }}/tree/">Source Code</a></li>
diff --git a/homepage/_layouts/docs.html b/homepage/_layouts/docs.html
new file mode 100644
index 0000000..2d915ca
--- /dev/null
+++ b/homepage/_layouts/docs.html
@@ -0,0 +1,37 @@
+---
+layout: default
+---
+
+<section class="py-5">
+ <div class="container px-5">
+ <div class="row">
+ <div class="col-lg-10 order-lg-2">
+ <h1 class="mb-4">{{ page.title }}</h1>
+
+ <div class="post-content">
+ {{ content }}
+ </div>
+ </div>
+ <div class="col-lg-2 order-lg-1">
+ <ul class="nav flex-column">
+ <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>
+ </ul>
+ </div>
+ </div>
+ </div>
+</section>
+
+<style type="text/css">
+ .md-content h1 {
+ display: none;
+ }
+ .post-content h2 {
+ margin-bottom: 1rem;
+ }
+ .post-content h3 {
+ font-size: 1.5rem;
+ margin-bottom: 1rem;
+ }
+</style>
diff --git a/homepage/_layouts/post.html b/homepage/_layouts/post.html
index 9dda375..25a00ab 100644
--- a/homepage/_layouts/post.html
+++ b/homepage/_layouts/post.html
@@ -6,6 +6,21 @@ layout: default
<div class="container px-5">
<h1 class="mb-4">{{ page.title }}</h1>
- {{ content }}
+ <div class="post-content">
+ {{ content }}
+ </div>
</div>
</section>
+
+<style type="text/css">
+ .md-content h1 {
+ display: none;
+ }
+ .post-content h2 {
+ margin-bottom: 1rem;
+ }
+ .post-content h3 {
+ font-size: 1.5rem;
+ margin-bottom: 1rem;
+ }
+</style>
diff --git a/homepage/assets/docs/005.png b/homepage/assets/docs/005.png
new file mode 100644
index 0000000..34e3af3
--- /dev/null
+++ b/homepage/assets/docs/005.png
Binary files differ
diff --git a/homepage/assets/docs/010.png b/homepage/assets/docs/010.png
new file mode 100644
index 0000000..8eb80e7
--- /dev/null
+++ b/homepage/assets/docs/010.png
Binary files differ
diff --git a/homepage/about.md b/homepage/docs/about.md
index 648190f..34e5a52 100644
--- a/homepage/about.md
+++ b/homepage/docs/about.md
@@ -1,12 +1,6 @@
---
-layout: post
+layout: docs
title: "About OpenTally"
---
<div class="md-content" markdown="1">{% include_absolute '../README.md' %}</div>
-
-<style type="text/css">
- .md-content h1 {
- display: none;
- }
-</style>
diff --git a/homepage/docs/options.md b/homepage/docs/options.md
index 569e1f0..4eabf97 100644
--- a/homepage/docs/options.md
+++ b/homepage/docs/options.md
@@ -1,23 +1,10 @@
---
-layout: post
+layout: docs
title: "Advanced options"
---
<div class="md-content" markdown="1">{% include_absolute '../docs/options.md' %}</div>
-<style type="text/css">
- .md-content h1 {
- display: none;
- }
- .md-content h2 {
- margin-bottom: 1rem;
- }
- .md-content h3 {
- font-size: 1.5rem;
- margin-bottom: 1rem;
- }
-</style>
-
<script>
document.querySelectorAll('.md-content table').forEach(el => el.classList.add('table'));
</script>
diff --git a/homepage/docs/quick-start.md b/homepage/docs/quick-start.md
new file mode 100644
index 0000000..1e69e0c
--- /dev/null
+++ b/homepage/docs/quick-start.md
@@ -0,0 +1,6 @@
+---
+layout: docs
+title: "Quick start guide"
+---
+
+<div class="md-content" markdown="1">{% include_absolute '../docs/quick-start.md' %}</div>
diff --git a/homepage/index.html b/homepage/index.html
index 1d96378..59e7de3 100644
--- a/homepage/index.html
+++ b/homepage/index.html
@@ -1,5 +1,6 @@
---
layout: default
+title: "OpenTally: Advanced online election counting"
---
<!-- Header-->
@@ -11,12 +12,12 @@ layout: default
<h1 class="display-5 fw-bolder text-white mb-2">Advanced online election counting</h1>
<p class="lead fw-normal text-white-50 mb-4">Count instant runoff and single transferable vote elections for free, no downloads or sign-up required</p>
<div class="d-grid gap-3 d-sm-flex justify-content-sm-center justify-content-xl-start">
- <a class="btn btn-primary btn-lg px-4 me-sm-3" href="{{ site.baseurl }}/stv/">Get Started</a>
- <a class="btn btn-outline-light btn-lg px-4" href="{{ site.baseurl }}/about.html">Learn More</a>
+ <a class="btn btn-primary btn-lg px-4 me-sm-3" href="{{ site.baseurl }}/stv/">Launch OpenTally</a>
+ <a class="btn btn-outline-light btn-lg px-4" href="{{ site.baseurl }}/docs/quick-start.html">Quick Start Guide</a>
</div>
</div>
</div>
- <div class="col-xl-5 col-xxl-6 d-none d-xl-block text-center"><img class="img-fluid rounded-3 my-5" src="{{ site.baseurl }}/assets/headerimg.png" alt="Screenshot of OpenTally" /></div>
+ <div class="col-lg-8 col-xl-5 col-xxl-6 d-block text-center"><img class="img-fluid rounded-3 my-5" src="{{ site.baseurl }}/assets/headerimg.png" alt="Screenshot of OpenTally" /></div>
</div>
</div>
</header>
Contact (issues, pull requests, etc.) at git@yingtongli.me. Generated by cgit.