Corrections per Nate W.

Signed-off-by: Josh Berkus <josh@agliodbs.com>

Author: jberkus

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

@@ -6,11 +6,7 @@ description: >
   Start using elekto for your organisation.
 ---
 
-Elekto is a DIY service, so in order to start using it, you're going to have to install it.
-
-Please see the following guides:
-
-Ways to install Elekto, any of:
+Elekto is a DIY service, so in order to start using it, you're going to have to install it:
 
 * [Developer Installation]({{< relref "devinstall.md" >}})
 * [Server Installation]({{< relref "installation.md" >}})

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

@@ -28,25 +28,25 @@ Currently, the only Oauth provider offered is GitHub.  Contributions of addition
 
 #### GitHub Oauth
 
-You must set up an "Oauth Application" that Elekto can use.  In GitHub, this is under Settings-->Developer Tools-->Oauth Applications.  Note that Oauth Apps are belong to *accounts* rather than organizations, so you'll want to set up an account with shared access in your infra team. We also recommend setting up a separate Oauth App for Elekto rather than re-using one created for other purposes, and giving each Elekto instance its own secret key.
+You must set up an "Oauth Application" that Elekto can use.  In GitHub, this is under Settings-->Developer Tools-->Oauth Applications.  Note that Oauth Apps are belong to *accounts* rather than organizations, so you'll want to set up an account with shared access in your infra team. We also recommend setting up a separate Oauth App for Elekto rather than re-using ones created for other purposes, and giving each Elekto instance its own secret key.
 
 The Oauth App must have the following settings:
 
 * Application Name: whatever you've named your Elekto instance
 * Homepage URL: the url of your Elekto instance
-* Authorization Callback URL: https://your.elekto.domain/oauth/github/callback  (note that this can be changed in ENV)
+* Authorization Callback URL: `https://your.elekto.domain/oauth/github/callback`  (note that this can be changed in ENV)
 
 Once you create the Oauth App, GitHub will create a ClientID for it, which you populate in GITHUB_CLIENT_ID in ENV.  You then create a new Oauth secret under the app and copy the value for that, and that gets populated in GITHUB_CLIENT_SECRET.
 
 #### GitHub Repository Webhook
 
-In order to receive changes from the repo, you need to add a webhook that pushes changes whenever you merge.  Webhooks are under "settings" for the individual repository (which also means you must be a repo onwer).  
+To receive changes from the repo, you need to add a webhook that pushes changes whenever you merge.  Webhooks are under "settings" for the individual repository (which also means you must be a repo owner).  
 
 The Webhook should have the following settings:
 
-* Payload URL: https://your.election.domain/v1/webhooks/meta/sync
-* Content Type: application/json
-* Shared Secret set to the same as META_SECRET
+* Payload URL: `https://your.election.domain/v1/webhooks/meta/sync`
+* Content type: application/json
+* Secret set to the same as META_SECRET
 * Enable SSL Verification
 * Just The Push Event
 * Check "Active" to turn it on
@@ -57,12 +57,12 @@ This "secret" is an arbitrary string that authenticates the push to the Elekto s
 
 Elekto is designed to accept its runtime configuration as ENV variables in its shell environment.  A sample `.env.example` file can be found in the base directory of the Elekto source.  These ENV configuration variables are not expected to change frequently, or at all, for any particular running Elekto instance.  Changing them generally requires restarting Elekto.
 
-All of these env variables need to be set before starting Elekto as a uwsgi application, or even in developer mode; without them, Elekto will error out and refuse to start. You can set this up however you please:
+All of these env variables need to be set before starting Elekto as a uWSGI application, or even in developer mode; without them, Elekto will error out and refuse to start. You can set this up however you please:
 
 * as the `.bashrc` for the elekto application user
 * as ENV variables for a container running Elekto
 * preloaded in a systemd unit file
-* injected through a ConfigMap and a Secret into an Kubernetes pod
+* injected through a ConfigMap and a Secret into a Kubernetes pod
 
 Since we use ENV for Elekto configuration, this does mean that Elekto must be launched under a shell.
 
@@ -86,11 +86,9 @@ Example: `production` or `development`
 
 **APP_KEY**
 
-*Optional* Seed string for Flask encryption if running Flask in standalone mode.  Not required if fronting with an HTTPS webserver.
+*Optional* Encryption seed for application cookies.  Deprecated; will be set automatically by Elekto in the future, but for now set it to a random 8byte+ value.
 
-Example: ``
-
-FIXME
+Example: `2400229255`
 
 **APP_DEBUG**
 
@@ -100,13 +98,13 @@ Example: `True` or `False`
 
 **APP_URL**
 
-*Optional* URL of the Elekto instance.  Used by some uwsgi and/or Nginx configurations.  Not used internally by Elekto.
+*Optional* URL of the Elekto instance.  Used by some uWSGI and/or Nginx configurations.  Not used internally by Elekto.
 
 Example: `http://elections.knative.dev`
 
 **APP_PORT**
 
-*Optional* Used in some uwsgi start scripts, and when running Flask in standalone mode.  Port on which to serve Elekto.
+*Optional* Used in some uWSGI start scripts, and when running Flask in standalone mode.  Port on which to serve Elekto.
 
 Example: `5000`
 
@@ -118,15 +116,15 @@ Example: `localhost`
 
 **APP_CONNECT**
 
-*Optional* Whether to serve uwsgi over HTTP or via a local unix socket.  Used by some startup scripts; see `entrypoint.sh` for an example.  
+*Optional* Whether to serve uWSGI over HTTP or via a local Unix socket.  Used by some startup scripts; see `entrypoint.sh` for an example.  
 
 Example: `http` or `socket`
 
 #### Database Connection
 
 **DB_CONNECTION**
 
-*Required* Which database connection type to use.  Currently only postgresql, mysql, and sqlite are supported.  
+*Required* Which database connection type to use.  Currently only PostgreSQL, MySQL, and SQLite backends are supported.  
 
 Example: `postgresql`, `mysql`, or `sqlite`
 
@@ -182,7 +180,7 @@ Example: `local`, `sidecar`
 
 **META_PATH**
 
-*Required* Local file location at which to store a clone of the election data repository.  This directory will be created by Elekto at sync time, so the application must have the ability to write to the parent directory.  May be absolute or relative; if relative, will be under the eletko source directory.  Defaults to `meta`.  For containers, a directory under `/tmp` is recommended to make sure the location is writeable.
+*Required* Local file location at which to store a clone of the election data repository.  This directory will be created by Elekto at sync time, so the application must have the ability to write to the parent directory.  The directory may be absolute or relative; if it is relative, it will be under the Eletko source directory.  Otherwise it defaults to `meta`.  For containers, a directory under `/tmp` is recommended to make sure the location is writeable.
 
 Example: `meta`, `/tmp/meta`
 
@@ -200,7 +198,7 @@ Example: `92a488d11c0d27bbfea0a97e3332e08a`
 
 #### Oauth Settings
 
-At this time, there are only settings available for GitHub because other Oauth sources haven't been implemented.  When other sources get added to Elekto, each will get their own configuration variables.
+At this time, there are only settings available for GitHub because other Oauth sources haven't been implemented.  When other sources get added to Elekto, each will get its own configuration variables.
 
 **GITHUB_REDIRECT**
 

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

@@ -10,7 +10,7 @@ This guide will help you create a development installation of Elekto on your lap
 
 ## Create a development environment
 
-The application is written in `python` using `flask` and `sqlalchemy`. This repository ships a `requirements.txt` and  a `environment.yml` for conda users.
+The application is written in Python using Flask and SQLAlchemy. This repository ships a `requirements.txt` and an `environment.yml` for conda users.
 
 ```bash
 # Installation with pip 
@@ -59,7 +59,8 @@ META_BRANCH=main
 META_SECRET=db5a951969c379e75d0bf15ad6ff8b4a36fbeb02  # same as webhook of the same meta repository
 ```
 
-Update the Oauth info, create an github oauth app if already not created.
+Update the Oauth info, create a GitHub Oauth app if already not created.
+
 ```bash
 GITHUB_REDIRECT=/oauth/github/callback
 GITHUB_CLIENT_ID=d79f002c1d2e3cf20521
@@ -68,10 +69,10 @@ GITHUB_CLIENT_SECRET=2f64fff6612c46f87314ad5bb81d05c8fd29c561
 
 #### Migrate and Sync DB with Meta
 
-The `console` script in the repository is used to perform all the table creations and syncing of the meta. 
+The `console` script in the repository is used to perform all the table creations and syncing of the meta files. 
 
 ```bash
-# to migrate the database from command line 
+# to migrate the database from the command line 
 python console --migrate 
 ```
 

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

@@ -12,20 +12,20 @@ This guide walks you through installing Elekto by hand on a server or VM.
 
 For Elekto to run in production, you need the following small application stack: 
 
-* The Elekto python/flask/uwsgi application
+* The Elekto python/flask/uWSGI application
 * A backing SQL database instance
 * A web proxy such as Nginx or Kubernetes Ingress
 * A GitHub repository
 * An Oauth authentication source
 
-Elekto can be installed either as a native application, or as a container.  The instructions below cover installation as a native application. For installation in a container, see [Kubernetes installation]({{< relref "kubernetes.md" >}})
+Elekto can be installed either as a native application or as a container.  The instructions below cover installation as a native application. For installation in a container, see [Kubernetes installation]({{< relref "kubernetes.md" >}})
 
 ## Installing Requirements and Python Binaries
 
-Elekto is a Python/Flask/uwsgi application developed in Python 3. Building it from source requires the following prerequisites, which should be installed using your OS's packaging system:
+Elekto is a Python/Flask/uWSGI application developed in Python 3. Building it from source requires the following prerequisites, which should be installed using your OS's packaging system:
 
 * Python3 Pip and supporting build tools (like gcc), or Conda
-* uwsgi server
+* uWSGI server
 * Database client libraries for your chosen database (see below)
 * git
 
@@ -41,11 +41,11 @@ conda env create -f environment.yml && conda activate elekto
 
 Please check the above build process carefully for error messages; the only acceptable errors are (a) warnings about out-of-date versions and (b) missing database libraries for the databases you're not using.
 
-It is completely possible that you could run Elekto using fastcgi instead of uwsgi, but at this time we have no documentation on how to do this.
+It is possible that you could run Elekto using fastcgi instead of uWSGI, but at this time we have no documentation on how to do this.
 
 ## Backing SQL Database
 
-Github stores ballots and some metadata in a designated SQL database, which is up to you to install and run.  Currently Elekto supports the following:
+Github stores ballots and some metadata in a designated SQL database, which is up to you to install and run.  Currently, Elekto supports the following:
 
 * PostgreSQL
 * MySQL (and its forks)
@@ -55,25 +55,25 @@ However, as Elekto uses SQLAlchemy, it can potentially support any SQL database
 
 Database requirements are very light, so it is completely feasible to run the database on the same server as the python application. The database server needs less than 2 CPUs, 1GB memory, and 25GB storage. You can also use a cloud database service; the included database support was chosen specifically because there are multiple cloud database services available.  In that case, you are likely to use the smallest size of cloud database available.
 
-The Elekto database user needs to have permissions to create tables. The database must be configured with user/password login.  Other forms of authentication are not yet supported.
+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.
 
 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
 
-Elekto runs in the python uwsgi web application server.  Uwsgi is not very scalable, though, and does not handle SSL connections.  As such, for anything other than developer mode, we recommend that you put a web server in front of it.
+Elekto runs in the python uWSGI web application server.  uWSGI is not very scalable, though, and does not handle SSL connections.  As such, for anything other than developer mode, we recommend that you put a web server in front of it.
 
 Nginx works well for this, whether as a standalone or as part of Kubernetes Ingress.  See the sample Nginx configuration in the installation directory of the Elekto repository for an example setup.  If running directly on a host with an Nginx proxy, you'll want to run Eletko in "socket" connection mode.  Other web servers would also work, but Nginx is the only sample configuration supplied.
 
-On Kubernetes, you'll want to access Elekto via Ingress.  See `installation/deployment` for an example of this.  In a Kubernetes setup, you want to run Elekto in http mode. 
+On Kubernetes, you'll want to access Elekto via Ingress.  See `installation/deployment` for an example of this.  In a Kubernetes setup, you want to run Elekto in `http` mode. 
 
 ## GitHub Repository
 
-Elekto's workflow is GitOps-based.  This means that, in order to use Elekto, you must have a GitHub (GitLab TBD) repository for Elekto to attach to.  This must be a repository you own and have administration rights on, as you will be setting up a webhook and directories.
+Elekto's workflow is GitOps-based.  This means that to use Elekto, you must have a GitHub (GitLab TBD) repository for Elekto to attach to.  This must be a repository you own and have administration rights on, as you will be setting up a webhook and directories.
 
 It does *not* need to be a repository that's exclusively dedicated to Elekto.  Most organizations using Elekto place its election metadata into a subdirectory of a repository that's used for other community documents (e.g. `knative/community/elections`).  Given that Elekto will refresh for every webhook push, however, it's probably better if it's not a repository that gets multiple commits per hour.
 
-See [Configuration]() for how to set up this GitHub repository, and the [Administration Guide]() for what files go into it.
+See [Configuration]({{< relref "configuration.md" >}}) for how to set up this GitHub repository, and the [Administration Guide]() for what files go into it.
 
 ## Oauth Authentication Source
 
@@ -83,8 +83,8 @@ See Configuration for how to configure this in GitHub.
 
 ## Other System Requirements
 
-Elekto does not require elevated privileges to run, so for security we recommend running it under an elekto, www, or python application account with restricted permissions.
+Elekto does not require elevated privileges to run, so for security, we recommend running it under an `elekto`, `www`, or `python` application account with restricted permissions.
 
 Elekto caches a copy of the election respository on disk, and as such needs a file location to which it can write, with storage equal to the storage size of a git clone of that repository.
 
-If you've completed everything in Installation, please proceed to [Configuration]().
+If you've completed everything in Installation, please proceed to [Configuration]({{< relref "configuration.md" >}}).