First batch of suggested edits

Account/data-storage-locality.md

@@ -4,4 +4,6 @@ Your data is distributed among our technology stack. You can find information ab
 
 You can find information about [Database Servers (MySQL)](https://docs.altis-dxp.com/cloud/database/) for content, [S3 Storage](https://docs.altis-dxp.com/cloud/s3-storage/) for assets, and [Backups](https://docs.altis-dxp.com/cloud/backups/) in the documentation.
 
-Information about your [Origin Location](https://docs.altis-dxp.com/cloud/origin-locations/) can be found within the Altis Dashboard; at the top of each environment's details pages, you can find the Region you're located within. All customer data is stored within this region, and is stored in durable, persistent storage across multiple [availability zones](https://docs.altis-dxp.com/cloud/architecture/) (data centres).
+Information about your [Origin Location](https://docs.altis-dxp.com/cloud/origin-locations/) can be found within the Altis Dashboard; at the top of each environment's details pages, you can find the Region you're located within. All customer data is stored within this region, and is stored in durable, persistent storage across multiple [availability zones](https://docs.altis-dxp.com/cloud/architecture/) (data centres).
+
+All your data is stored isolated from others, with fully dedicated infrastructure for each customer.

Common Errors and Issues/build-size.md

@@ -7,13 +7,13 @@ Error: The build image size (... MB) exceeds the maximum allowed size for your e
 
 ```
 
-Then your build image has gone over the build size limit, and must be brought down to below 640MB.
+Then your build image has exceeded the build size limit, and must be reduced to below 640MB.
 
 You can look at the following areas to reduce build size:
 
 - Add `--prefer-dist` to the composer install command
 - If you are building JS / CSS assets with tools installed via npm or yarn ensure you're removing `node_modules` afterwards.
-- Once the above is done, ensure you clear the build cache in Altis Dashboard before re-trying the deployment (contact support to clear the build cache)
+- Once the above is done, ensure you clear the build cache in the Altis Dashboard before re-trying the deployment (contact support to clear the build cache)
 
 
 In some cases, a large file may have been committed to your repository and is being deploy; so check your code repository for large files.
@@ -27,4 +27,4 @@ To remove your Node modules directory via your build-script, you can add somethi
 find . -name 'node_modules' -type d -prune -exec rm -rf '{}' +
 ```
 
-You can read more about build script limitations in this article: https://docs.altis-dxp.com/cloud/build-scripts/#limits
+You can read more about build script limitations in this article: https://docs.altis-dxp.com/cloud/build-scripts/#limits

Common Errors and Issues/index-occurring.md

@@ -1,19 +1,29 @@
 #  ElasticSearch Index: Error: An index is already occurring. Try again later. 
 
-If you recieve the error `ElasticSearch Index: Error: An index is already occurring. Try again later. ` when performing an ElasticSearch reindex, it's possible the indexing flag for an in-progress index has got stuck. The resulting error will occur: 
+If you receive the error `ElasticSearch Index: Error: An index is already occurring. Try again later. ` when performing an ElasticSearch reindex, it's possible the indexing flag for an in-progress index has got stuck. The resulting error will occur:
+
 ```
 Error: An index is already occurring. Try again later.
 ```
+
 In such a case, you can clear the flag by running the following:
+
 ```
 wp elasticpress clear-sync 
 ```
-Alternatively, if the above doesn't resolve the issue, it can also be stuck in a [WordPress pransient](https://developer.wordpress.org/apis/transients/). If so you can try the following:
+
+Alternatively, if the above doesn't resolve the issue, it can also be stuck 
+in a [WordPress pransient](https://developer.wordpress.org/apis/transients/). If so, you can try the following:
+
 ```
 wp transient delete ep_wpcli_sync --network
 ```
+
 Occasionally this value can also be stored in the object cache. Flushing the object cache should be performed with caution when working on live environments. 
 You can flush your object cache via a new CLI Session, see: https://docs.altis-dxp.com/cloud/dashboard/cli/ and run the following:
+
 ```
 wp cache flush
-```
+```
+
+**Note that flushing the object cache can have a significant impact on performance, so we recommend you only do this when necessary.** 

Common Errors and Issues/integrity-check.md

@@ -7,31 +7,39 @@ Failed to find a valid the 'integrity' attribute for resource...
 ```
 
 Is a browser security error. The reason that these problems occur is due to a hash mismatch due to the SRI functionality within the [Altis Security module][https://github.com/humanmade/altis-security].
-
 
 When Altis outputs scripts and styles onto the page, it includes a hash for the SRI, in the integrity attribute. This hash is generated within PHP by reading the file from disk, applying hashing algorithms, and then storing it in the object cache keyed against the file path and the version specified in the code. (In other words, it calls `wp_cache_set( '/content/your/file.css?1.2.3.4', 'sha384-...', 'altis_integrity' )`)
 
 In addition, static files are cached by the CDN, where the file is cached for one year using the path and the query string as the cache key. 
 
-In cases where the contents of a file are updated, the version within the codebase needs to be changed in order to invalidate both of these caches. If the version isn't updated, the CDN will continue to serve a stale version of the file (as the CDN's cache key won't have changed), and the backend should also continue to serve the old hash (as it pulls it from the cache). This causes the file to continue to be served correctly but without the latest updates.
+In cases where the contents of a file are updated, the version within the 
+codebase needs to be changed in order to invalidate both of these caches. If 
+the version isn't updated, the CDN will continue to serve a stale version of 
+the file (as the CDN's cache key won't have changed), and the backend 
+will also continue to serve the old hash (as it pulls it from the cache). 
+This causes the file to continue to be served correctly but without the latest updates.
 
-
+If the CDN and the backend cache become out of sync, this can cause the file 
+to not be loaded. This occurs only in the edge case where the file is 
+updated without changing the version number, and either the object cache 
+entry is evicted or cleared or the CDN cache entry is evicted. Either of 
+these will cause the file contents as seen by the CDN and the backend to not
+match, and the hashes to mismatch. (It's also possible for your browser to 
+cache this, however, this only causes issues when you're doing things like 
+CDN invalidation.)
 
-If the CDN and the backend cache become desynchronised, this can cause the file to not be loaded. This occurs only in the edge case where the file is updated without bumping the version number, and either the object cache entry is evicted or cleared or the CDN cache entry is evicted. Either of these will cause the file contents as seen by the CDN and the backend to not match, and the hashes to mismatch. (It's also possible for your browser to cache this, however, this only causes issues when you're doing things like CDN invalidation.)
 
-
+For this reason, it's important that whenever the file changes, the version 
+number must be changed too. This ensures that this edge case cannot be 
+hit as well as making sure that the correct content is being served to users.
 
-For this reason, it's important that whenever the file changes, the version number must be changed as well. This ensures that this edge case cannot be hit, in addition to making sure that the correct content is being served to users.
-
-
+Using timestamps for the versions should be OK, but it's possible that this 
+may cause problems with the multi-server architecture of Altis. Because 
+there are multiple servers serving your files, the timestamps for each file 
+could mismatch; this shouldn't normally cause an issue.
 
-Using timestamps for the versions should be OK, but it's possible that this is causing problems with the multi-server architecture of Altis. Because there are multiple servers serving your files, the timestamps for each file could mismatch; this shouldn't cause an issue.
-
-Our advice is to generate this within the build process: https://docs.altis-dxp.com/cloud/static-file-caching/
-
-To resolve these issues, ensure all Altis Modules are up to date with the `--with-all-dependencies` flag.
-
-
+Our advice is to generate the version string within the build process: 
+https://docs.altis-dxp.com/cloud/static-file-caching/
 
 Read more about integrity checking:
 
@@ -42,4 +50,4 @@ https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
 
 Further steps on debugging:
 
-https://docs.altis-dxp.com/guides/getting-help-with-altis/debugging/
+https://docs.altis-dxp.com/guides/getting-help-with-altis/debugging/

Common Errors and Issues/uploading-files-fails.md

@@ -1,7 +1,5 @@
 #  Uploading files displays 'cannot upload this file type' 
 
-
-
 The default WordPress behaviour will only allow files of specified file-types to be uploaded. If a file is uploaded that is not in the list of permitted file types, WordPress will display the error 'Sorry, you are not allowed to upload this file type'.
 
 What is the default allowed list?
@@ -10,5 +8,8 @@ What is the default allowed list?
 
 Can this list be changed?
 
-WordPress allows you to add file types to the above list, to do this, go to the Network Admin of your site, then go to 'Settings'. Find the field for "Upload file types" and add the file types you wish to upload to the list.
-Once you save the settings, you'll be able to freely upload files with the newly added file extension.
+WordPress allows you to add file types to the above list. To do this, go to
+the Network Admin of your site, then go to 'Settings'. Find the field for
+"Upload file types". Add the file types you wish to upload to the list. Once 
+you save the settings, you'll be able to freely upload files with the
+newly added file extension.

Developing on Altis/custom-php-extensions.md

@@ -2,4 +2,4 @@
 
 No. It's not possible to customise the PHP extension configuration. 
 
-We are not accepting requests for PHP Extensions, however, let us know that you're interested in a specific PHP extention. Let us know tell us about your requirements and how you may use the extension. To request a feature, head on over to our roadmap, and submit your ideas - https://dashboard.altis-dxp.com/roadmap
+We are not accepting requests for PHP Extensions, however, let us know that you're interested in a specific PHP extension. Tell us about your requirements and how you may use the extension. To request a feature, head on over to our roadmap, and submit your ideas - https://dashboard.altis-dxp.com/roadmap   

Developing on Altis/importing-assets.md

@@ -4,18 +4,23 @@ Assets uploaded to Altis are stored in dedicated asset storage, powered by Amazo
 
 This guide will help you in migrating smaller sets of assets to an Altis Environment. If you're performing a large data import or are migrating onto our platform, [contact Altis support](https://docs.altis-dxp.com/guides/getting-help-with-altis/). For example, if your assets already exist on S3, support can arrange an S3 to S3 transfer. 
 
-To import new or delta assets into your Altis Environment, the process will depend on the total size of the assets you wish to import. For large sets of assets (>=10GB), [contact Altis support](https://docs.altis-dxp.com/guides/getting-help-with-altis/), and we will import them on your behalf. For small assets imports, you can use the [CLI via Altis Dashboard](https://docs.altis-dxp.com/cloud/dashboard/cli/).
+To import new or delta assets into your Altis Environment, the process will depend on the total size of the assets you wish to import. For large sets of assets (10GB or more), [contact Altis support](https://docs.altis-dxp.com/guides/getting-help-with-altis/), and we will import them on your behalf. For small assets imports, you can use the [CLI via Altis Dashboard](https://docs.altis-dxp.com/cloud/dashboard/cli/).
 
 Note: The Sandbox has a maximum 10GB of disk space available mounted to `/usr/src/app/`.
 
 ## Transfer assets to the Sandbox
 
 For those comfortable installing and using CLI tools locally, you can copy files to the Sandbox, via the [local Altis CLI tool](https://github.com/humanmade/altis-cli). This will allow you to `scp` directly to the Sandbox. The Altis CLI is currently experimental with minimal documentation, so debugging issues with this method will have to be self-guided.
 
-Alternatively, you can use `wget` to download files to the sandbox. To download files with `wget`, you will need an accessible link to the files.
+Alternatively, you can use `wget` to download files to the sandbox. To download files with `wget`, you will need a web accessible link to the files.
 
 ## Sync the assets to S3
 
 Once you have your assets in place, you can run `wp s3-uploads` to copy the assets to S3. The target destination needs to use an S3 location. To get your environment S3 bucket info, run `env | grep S3_UPLOADS_BUCKET`, and this will return the S3 Bucket for this environment, which you will use as part of the target destination. 
-Transferring the assets to S3 would be done with a command that looks like so; `wp s3-uploads cp ./myassets s3://S3_UPLOADS_BUCKET_VALUE/uploads/sites/01`. 
+Transferring the assets to S3 would be done with a command that looks like this; 
+
+```shell
+wp s3-uploads cp ./myassets s3://S3_UPLOADS_BUCKET_VALUE/uploads/sites/02
+```
+
 

Developing on Altis/importing-database.md

@@ -1,6 +1,7 @@
 # How do I import an external database into an Altis environment?
 
-To import an external database dump into an Altis environment, the process will depend on how large the dump is you wish to import. For large database dumps (>=10GB), [contact Altis support](https://docs.altis-dxp.com/guides/getting-help-with-altis/), and we will import the database on your behalf. To import smaller databases, you'll predominately use the [CLI via Altis Dashboard](https://docs.altis-dxp.com/cloud/dashboard/cli/). 
+To import an external database dump into an Altis environment, the process 
+will depend on how large the dump is you wish to import. For large database dumps (10GB or more), [contact Altis support](https://docs.altis-dxp.com/guides/getting-help-with-altis/), and we will import the database on your behalf. To import smaller databases, you'll predominately use the [CLI via Altis Dashboard](https://docs.altis-dxp.com/cloud/dashboard/cli/). 
 
 Note: The Sandbox has a maximum 10GB of disk space available mounted to `/usr/src/app/`.
 
@@ -10,7 +11,7 @@ The first step is to copy the database dump to your Altis environment sandbox so
 
 For those comfortable installing and using CLI tools locally, you can copy files to the Sandbox, via the [local Altis CLI tool](https://github.com/humanmade/altis-cli). This will allow you to `scp` directly to the Sandbox. 
 
-Another method would be to run `wget` from the sandbox. You must have a presigned download link to your database dump. `wget` is preinstalled on the Sandbox.
+Another method would be to run `wget` from the sandbox. You must have a pre-signed download link to your database dump. `wget` is preinstalled on the Sandbox.
 
 The target location for your database dump on the Sandbox should be `/usr/src/app/`, the home directory of your application. This volume's storage capacity is 10gb.
 
@@ -28,7 +29,8 @@ When importing databases into non-production environments, a search-replace may
 
 Use [`wp search-replace`](https://developer.wordpress.org/cli/commands/search-replace/) to update URLs from their original to your Altis domain. 
 
-E.G `wp search-replace example.com example-dev.altis.cloud --dry-run` - note the `--dry-run` flag, this is good practice prior to any search replace to review the replacements to be made. Also note the omittance of any HTTP protocol in the URLs - if you run a search-replace that include the protocol, this may cause irreversible issues to the database, so it avoid using them.
+E.G `wp search-replace example.com example-dev.altis.cloud --dry-run` - note 
+the `--dry-run` flag, this is good practice prior to any `search replace` operation to review the replacements to be made. Also note the HTTP protocol is omitted from the URLs - if you run a search-replace that include the protocol, this may cause irreversible issues to the database, so avoid using them.
 
 Finally, flush the object cache! Run `wp cache flush`. 
 

Developing on Altis/move-bulk-uploads.md

@@ -17,9 +17,10 @@ $ aws s3 ls s3://copied-uploads-bucket-path/
 ```
 
 This should return a list of directories you have access to.
-Operations
 
-The most common operations are `$ aws s3 cp *src dest*` and `$ aws s3 sync *src dest*.` They can be used larg
+## Operations
+
+The most common operations are `$ aws s3 cp *src dest*` and `$ aws s3 sync *src dest*.`.
 
 The `cp` command copies objects from the source directory to the destination.
 
@@ -28,12 +29,13 @@ The `sync` command copies any missing objects from the source to the destination
 For more advanced operations, see the AWS CLI documentation:
 
 https://docs.aws.amazon.com/cli/latest/reference/s3/#single-local-file-and-s3-object-operations
-Example
+
+## Example
 
 A common use case is a change of sub-site ID, so you want to copy the uploads from `uploads/sites/10/` to `uploads/sites/11/`
 
 Assuming the destination directory is empty the command would look like this:
 
 ```
 $ aws s3 cp s3://copied-uploads-bucket-path/uploads/sites/10/ s3://copied-uploads-bucket-path/uploads/sites/11/ --recursive --acl=public-read
-```
+```

Developing on Altis/private-packages.md

@@ -10,4 +10,6 @@ composer config --auth http-basic.my.yoast.com token {token}
 
 You should see a `auth.json` file in the project's directory - you can commit this, and it should authenticate correctly in the build. 
 
-`auth.json` is prevented from being accessed directly via the servers, so this won't be exposed publicly.
+`auth.json` is prevented from being accessed directly via the servers, so this won't be exposed publicly.
+
+[OWAIN, Should this mention secrets now we have them? - ie generate the auth.json as part of the build script tso it is not committed to the repo?]

Developing on Altis/using-altis-cli.md

@@ -6,8 +6,9 @@ Follow up the setup readme here: https://github.com/humanmade/altis-cli
 
 Once done, configure the cli tools with `altis-cli config setup`. If this returns `Saved configuration!`, the next time we run a command your browser will open a window to authorize the Altis CLI with your Altis Dashboard user. For example run `altis-cli stack info myenvironment-dev-01`; this will open a browser window, and follow the prompts.
 
-This completes the setup, and you'll be able 
-## 
+This completes the setup, and you'll be able to run commands.
+
+## Copying Files??
 
 Copying files from your local computer to the Sandbox is fairly straightforward.