From 0d9976569213e078325ee860ab9e7abe37749420 Mon Sep 17 00:00:00 2001
From: Daniel Gerhardt <code@dgerhardt.net>
Date: Fri, 19 Jan 2018 23:31:23 +0100
Subject: [PATCH] Improve wording and add missing commas in the documentation
---
src/site/markdown/development.md | 4 ++--
src/site/markdown/development/caching.md | 4 ++--
src/site/markdown/installation.md | 30 ++++++++++++------------
src/site/markdown/upgrade.md | 12 +++++-----
4 files changed, 25 insertions(+), 25 deletions(-)
diff --git a/src/site/markdown/development.md b/src/site/markdown/development.md
index 6535d1100..59d849039 100644
--- a/src/site/markdown/development.md
+++ b/src/site/markdown/development.md
@@ -31,7 +31,7 @@ You can create a web archive (`.war` file) by running a single command:
## Running
ARSnova builds are setup up to automatically download the Java Servlet container Jetty for development.
-Run the following command to download the dependencies and startup the backend with Jetty:
+Run the following command to download the dependencies, and startup the backend with Jetty:
$ mvn jetty:run
@@ -50,7 +50,7 @@ Apart from mirroring GitLab CI triggers various jobs to:
* execute unit tests
* deploy to our staging/production servers
-In addition to GitLab CI for our internal repositories we use Travis CI which is able to run against merge requests on GitHub.
+In addition to GitLab CI for our internal repositories, we use Travis CI which is able to run against merge requests on GitHub.
Travis CI only runs unit tests for the backend.
The current build status for the master branch:
diff --git a/src/site/markdown/development/caching.md b/src/site/markdown/development/caching.md
index 01d4a81cc..163735fc1 100644
--- a/src/site/markdown/development/caching.md
+++ b/src/site/markdown/development/caching.md
@@ -5,14 +5,14 @@ Please read about Spring Framework's [Cache Abstraction](http://docs.spring.io/s
## What should get cached?
-The short answer: All data that is written once and read multiple times. In ARSnova, there is an inherent `1:n` relationship between teachers and students. This makes everything the teacher creates a candidate for caching. But there are more opportunities, like students' answers which are mostly written once and cannot be changed afterwards. Be aware though that in this case, once a new answer comes in, the cache has to be invalidated. With many students answering questions at the same time the effects of caching go away since the cache is invalidated all the time.
+The short answer: All data that is written once and read multiple times. In ARSnova, there is an inherent `1:n` relationship between teachers and students. This makes everything the teacher creates a candidate for caching. But there are more opportunities like students' answers which are mostly written once and cannot be changed afterwards. Be aware though that in this case, once a new answer comes in, the cache has to be invalidated. With many students answering questions at the same time, the effects of caching go away since the cache is invalidated all the time.
While caching provides an opportunity to greatly speed up the execution of various requests, it does come with a price: You have to think of all cases were the cached data might become stale.
## How to design your objects
-Caching should only be used with domain objects, where the `hashCode` and `equals` methods are provided. This makes it easy to update or delete cache entries. As you recall from the documentation, cache keys are based on a method's parameters. If you use base objects like `String` or `Integer`, you will have to manually provide a key through the Spring Expression Language (SpEL). As you can see from the following example, such keys can become quite complicated:
+Caching should only be used with domain objects where the `hashCode` and `equals` methods are provided. This makes it easy to update or delete cache entries. As you recall from the documentation, cache keys are based on a method's parameters. If you use base objects like `String` or `Integer`, you will have to manually provide a key through the Spring Expression Language (SpEL). As you can see from the following example, such keys can become quite complicated:
```java
@Cacheable(value = "notverycacheable", key = "#p0.concat('-').concat(#p1).concat('-').concat(#p2)")
diff --git a/src/site/markdown/installation.md b/src/site/markdown/installation.md
index c94bfe38c..755cf4a3d 100644
--- a/src/site/markdown/installation.md
+++ b/src/site/markdown/installation.md
@@ -1,7 +1,7 @@
# Installation
This document describes the necessary steps to install ARSnova Backend.
-In case you are viewing this file from the repository please make sure you are on the corresponding `x.y-stable` branch for the target version.
+If you are viewing this file from the repository, please make sure you are on the corresponding `x.y-stable` branch for the target version.
## Requirements
@@ -18,7 +18,7 @@ For Debian 8 you need to enable the backports repository to install Java 8:
### Hardware
-While the hardware requirements highly depend on the number of simultaneous users we suggest to provide at least 2 CPU cores and 4 GiB memory to the system ARSnova will be running.
+While the hardware requirements highly depend on the number of simultaneous users, we suggest to provide at least 2 CPU cores and 4 GiB memory to the system running ARSnova.
This configuration would support up to 500 users.
@@ -61,7 +61,7 @@ Most of this software can easily be installed on Linux systems using the distrib
* Debian: `# apt-get install -t jessie-backports nginx openjdk-8-jre && apt-get install libapr1 tomcat8`
* Ubuntu: `# sudo apt-get install couchdb libapr1 nginx openjdk-8-jre tomcat8`
-While running ARSnova without a reverse proxy is possible we do not recommend to do so.
+While running ARSnova without a reverse proxy is possible, we do not recommend to do so.
A reverse proxy significantly simplifies the setup of HTTPS and allows running Websocket connections over the default HTTP(S) port.
@@ -69,7 +69,7 @@ A reverse proxy significantly simplifies the setup of HTTPS and allows running W
Install CouchDB:
Depending on your operation system or distribution you might need to compile CouchDB from source code.
-In this case follow the CouchDB's
+In this case follow CouchDB's
[installation guide](http://docs.couchdb.org/en/1.6.1/install/index.html).
Before you proceed, make sure that CouchDB is up and running:
@@ -91,23 +91,23 @@ To set up the database, run:
This will create the database along with all required view documents.
-CouchDB is now usable for ARSnova but there a still a few things that should be setup for security and performance reasons.
+CouchDB is now usable for ARSnova, but there are still a few things that should be setup for security and performance reasons.
We recommend that you make the following adjustments to the CouchDB configuration `local.ini` which is usually located in either `/etc/couchdb` or `/usr/local/etc/couchdb` depending on the installation method.
-First make sure the CouchDB daemon only listens to local connections by setting `bind_address` in the `httpd` section to `127.0.0.1`.
+First, make sure the CouchDB daemon only listens to local connections by setting `bind_address` in the `httpd` section to `127.0.0.1`.
Next, append the following section which instructs CouchDB to cleanup at night.
[compactions]
_default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "01:00"}, {to, "05:00"}]
-To make compaction effective you need to reduce the number of revisions saved per document.
-As long as CouchDB is not clustered you can significantly reduce storage usage by setting a limit of 5.
+To make compaction effective, you need to reduce the number of revisions saved per document.
+As long as CouchDB is not clustered, you can significantly reduce storage usage by setting a limit of 5.
$ curl -X PUT -d "5" http://localhost:5984/arsnova/_revs_limit
### Java & Tomcat
-To make sure ARSnova has access to the memory provided by the system you need adjust the Java settings for Tomcat.
+To make sure ARSnova has access to the memory provided by the system, you need adjust the Java settings for Tomcat.
Increase the initial and maximum heap sizes by adding `-Xms3072m -Xmx3072m` to the Java start up parameters used by Tomcat.
On Debian-based systems this is done by appending
@@ -115,11 +115,11 @@ On Debian-based systems this is done by appending
to `/etc/default/tomcat8`.
For most other distributions append this to `setenv.sh` in Tomcat's `bin` directory.
-Adjust the values based on the memory available to the system but make sure reserve 1 GiB for the operating system, web server and database system.
+Adjust the values based on the memory available to the system, but make sure to reserve 1 GiB for the operating system, web server, and database system.
By default, Tomcat listens on a public interface.
-If you follow our recommendation and use a reverse proxy you should change the configuration so Tomcat only accepts requests from localhost.
-Open `/etc/tomcat8/server.xml` and look for `<Connector port="8080" ...>` and change it to:
+If you follow our recommendation to use a reverse proxy, you should change the configuration so Tomcat only accepts requests from localhost.
+Open `/etc/tomcat8/server.xml`, look for `<Connector port="8080" ...>`, and change it to:
<Connector port="8080" address="127.0.0.1" ...>
@@ -130,7 +130,7 @@ The ARSnova Backend application is contained in a single file: the web archive (
You can download the latest version from our
[GitHub releases page](https://github.com/thm-projects/arsnova-backend/releases).
-To deploy the backend on the Tomcat Servlet container, copy the file to Tomcat's webapp directory and name it `api.war`.
+To deploy the backend on the Tomcat Servlet container, copy the file to Tomcat's webapp directory, and name it `api.war`.
Check that the application is deployed correctly by sending a HTTP request:
@@ -184,14 +184,14 @@ Add the following lines to the `VirtualHost` section of the file:
ProxyPassReverse ws://localhost:8090/socket.io/
</Location>
-To enable the required Apache HTTP Server modules simply type:
+To enable the required Apache HTTP Server modules, simply type:
# a2enmod proxy
# a2enmod proxy_http
# a2enmod proxy_wstunnel
# a2enmod rewrite
-At last, disable the default site configuration and enable the newly created one:
+At last, disable the default site configuration, and enable the newly created one:
# a2dissite default
# a2ensite arsnova
diff --git a/src/site/markdown/upgrade.md b/src/site/markdown/upgrade.md
index 5b788d0e2..966f78eb0 100644
--- a/src/site/markdown/upgrade.md
+++ b/src/site/markdown/upgrade.md
@@ -1,12 +1,12 @@
# Upgrading ARSnova
This document describes the necessary steps to upgrade ARSnova Backend.
-In case you are viewing this file from the Repository please make sure you are on the corresponding `x.y-stable` branch for the target version.
+If you are viewing this file from the Repository, please make sure you are on the corresponding `x.y-stable` branch for the target version.
## Database Backup
-To be able to revert to the previous installed version you should backup your CouchDB database.
+To be able to revert to the previous installed version, you should backup your CouchDB database.
All data is stored in `arsnova.couch` which is usually located either in `/var/lib/couchdb` or `/usr/local/var/lib/couchdb`.
Optionally, you can backup the whole directory which will require significantly more space.
Otherwise, this additional data can be regenerated by CouchDB.
@@ -17,9 +17,9 @@ Otherwise, this additional data can be regenerated by CouchDB.
Most ARSnova minor releases require modifications to the database.
We provide the [ARSnova Setup Tool](https://github.com/thm-projects/arsnova-setuptool/releases) to handle these changes.
Please make sure you download the corresponding release for the target version.
-Usually, there are no database modifications for patch releases so you can use Setup Tool version 2.5.0 for Backend 2.5.1.
+Usually, there are no database modifications for patch releases, so you can use Setup Tool version 2.5.0 for Backend 2.5.1, for example.
-Unpack the downloaded archive and run the following commands in the extracted directory:
+Unpack the downloaded archive, and run the following commands in the extracted directory:
$ python tool.py
$ python migration.py
@@ -36,12 +36,12 @@ We suggest you review the corresponding [arsnova.properties.example](../../main/
Copy the web archive (`.war` file) for the new backend version into Tomcat's `webapps` directory.
It is usually located at either `/var/lib/tomcatX/webapps` or `/opt/tomcatX/webapps`.
Make sure you use the same name you chose when installing ARSnova (we suggest `api.war`) and override the existing file.
-By default, Tomcat automatically deploys the updated application but nevertheless we recommend restarting Tomcat to make sure no unnecessary data is kept in memory.
+By default, Tomcat automatically deploys the updated application, but nevertheless we recommend restarting Tomcat to make sure no unnecessary data is kept in memory.
## Frontend Upgrade
-While we try to keep compatibility breaking changes to the API to a minimum we suggest to always use a version of Mobile corresponding to the backend's version.
+While we try to keep compatibility breaking changes to the API to a minimum, we suggest to always use a version of Mobile corresponding to the backend's version.
## Final Steps
--
GitLab