Merge pull request #13 from nextcloud/jb-architecture

Typos and rewrite

1 files changed, 30 insertions, 31 deletions

diff --git a/doc/architecture.md b/doc/architecture.md
index 44660c9..2a39f09 100755
--- a/doc/architecture.md
+++ b/doc/architecture.md
@@ -2,22 +2,22 @@
 
 ## Overview
 Lookup-Servers can be configured on the Nextcloud Admin page. By default some
-are provided by default but they can be removed and custom Lookup-Servers can
-be added. Lookup-Servers work as public telephone book for Nextcloud users.
-Nextcloud users can optionally choose to publish some of their personal data
-like name, city, email and more on a Lookup-Server. This has the benefit that
-they can be found by other Nextcloud users to simplify for example sharing.
+are provided, but they can be removed and custom Lookup-Servers added as required. 
+Lookup-Servers work as public telephone book for Nextcloud users.
+Nextcloud users can optionally choose to publish some of their personal data such as
+name, city, email and more on a Lookup-Server; this has the benefit of making it
+much easier to be found by other Nextcloud users in order to simplify, for example, sharing.
 
 ## Security
-Communication with Lookup-Servers provide should be SSL encrypted and they 
-provide basic authentication via public key signing of the personal data.
-Additionally Lookup-Servers provide some protection against user data
-scraping. But the overall idea is that all information that a user chooses
-to publish on a Lookup-Server is considered public and and is published
-optionally to be found by others. When a user decided to publish its own
-data a public key is obtained from its Nextcloud instance (deducted from
-their federated cloud id). This public key is used to verify
-the signature of the send data.
+Communication with Lookup-Servers should be SSL encrypted and   
+provide basic authentication via public key signing of personal data.
+Additionally, Lookup-Servers provide some protection against user data
+scraping, but the overall idea is that all information that a user chooses
+to publish on a Lookup-Server is considered public and is published optionally 
+and accordingly to be found by others. When a user decides to publish their
+data, a public key is obtained from their Nextcloud instance (deduced from
+their federated cloud id). This public key is used to verify the signature 
+of the sent data.
 
 ### Key requirements
 The length of the key must be at least 2048 bits. And the digest algorithm
@@ -26,11 +26,10 @@ is `sha512`. The signature algorithm is also `sha512`.
 
 ## REST
 Communication between Nextcloud servers and Lookup-Servers happens via REST 
-calls. The following REST calls exists:
+calls. The following REST calls exist:
 
 ### Create user
-This can be used by a user to create a record and initially publish their own
-information.
+This can be used by a user to create a record and initially publish their information.
 
 Endpoint: http://dev/nextcloud/lookup-server/server/users
 Method: POST
@@ -58,7 +57,7 @@ Data: JSON blob
 
 ### Update user
 Updating a record is the same as publishing a new record. Unchanged fields will
-not be touched. New fields will be added (and if possible verified). And fields
+not be touched, new fields will be added (and if possible verified) and fields
 no longer in the update request will be removed.
 
 Endpoint: http://dev/nextcloud/lookup-server/server/users
@@ -86,7 +85,7 @@ Data: JSON blob
 ```
 
 ### Delete user
-Deleting is simply removing all additional info.
+Deleting is simply removing all user-published info.
 
 Endpoint: http://dev/nextcloud/lookup-server/server/users
 Method:DELETE
@@ -106,7 +105,7 @@ Data: JSON blob
 }
 ```
 
-Note the server will still keep the cloud id in order to properly propagate this.
+Note: The server will still keep the cloud id in order to properly propagate this.
 But all other personal data will be removed.
 
 ### Search users
@@ -120,11 +119,11 @@ Example:
 curl -X GET http://lookup:foobar@dev/nextcloud/lookup-server/replication?timestamp=123456\&page=0  
 
 ## High availability
-Several Lookup-Server can do master-master replication and sync their data. 
+Several Lookup-Servers can do master-master replication and sync their data. 
 This is useful to keep the data between different servers in sync. A user only
-need to publish, update or delete the record only one one server but the data
-will be available on different servers. The url of the other servers and the
-credentials of the own server needs to be configured in the config.php file.
+needs to publish, update or delete the record on one server and the data
+will automatically replicated and available on different servers. The URL of the 
+other servers and the credentials of their server needs to be configured in the config.php file.
 
 ## DB Structure
 
@@ -152,17 +151,17 @@ This table holds email verification data
 
 ## Karma
 The visibility of a user in the search call depends on the Karma of a user. 
-Karma is the number of verified fields. For example a user that has verified
-their email and twitter has a karma of 2.
+Karma is the number of verified fields, for example a user that has verified
+their email and Twitter has a Karma of 2.
 
-Only entries with a karma of at least 1 show up in search. The results are
-ordered by karma.
+Only entries with a Karma of at least 1 will show up in a search. The results are
+ordered by Karma.
 
 
 ## Verification
 
 ### Email
-Every time a new user is registered or an existing user changes the email
-address the emailstatus is set to unverified. A verification email is send to
-the new address. Once the link in that email is clicked the email address is
+Every time a new user is registered or an existing user changes their email
+address, the emailstatus is set to unverified. A verification email is sent to
+the new address. Once the link in that email is clicked, the email address is
 set to verified again.