Less verbosity in upgrading guide

docs/en/04_Changelogs/4.0.0.md

@@ -34,15 +34,14 @@ guide developers in preparing existing 3.x code for compatibility with 4.0
   prominently featuring ReactJS to develop highly functional CMS content areas. A new standard form schema
   API has been developed to allow back-end PHP constructed forms to scaffold themselves within ReactJS
   powered sections.
-* CMS CSS has been re-developed using bootstrap 4 as a base. See the
-  [silverstripe blog post](https://www.silverstripe.org/blog/a-frameworks-framework-why-silverstripe-4-will-use-bootstrap/).
+* CMS CSS has been re-developed using bootstrap 4 as a base 
+  ([blog post](https://www.silverstripe.org/blog/a-frameworks-framework-why-silverstripe-4-will-use-bootstrap/))
 * Asset admin has been replaced with a purely ReactJS powered upgrade, and split out
-  [into a new module](https://github.com/silverstripe/silverstripe-asset-admin/)
+  module called [asset-admin](https://github.com/silverstripe/silverstripe-asset-admin/). You'll need to add this to your `composer.json` to retain file management capabilities for your CMS authors.
 * Versioning is now a much more powerful feature, with the addition of campaigns to allow batches of related
   or inter-dependent objects to be published as a single act. Dependencies between versioned objects can be
   declared using the new ownership API, so that developers can ensure that relational consistency is
-  maintained during publishing. This new system can be managed via the new "Campaigns" CMS section.
-  See the [silverstripe blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/).
+  maintained during publishing. This new system can be managed via the new "Campaigns" CMS section ([blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/))
 * Template variable casting (e.g. `<h1>$Title</h1>`) is enforced by default, which will ensure safe HTML encode
   unless explicitly opted out.
 * Themes are now configured to cascade, where you can specify a list of themes, and have the template engine
@@ -187,15 +186,11 @@ After:
 
 
 If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT`
-instead, or if used in an actual XML file use `.CDATA`.
-
-See the [Template casting](/developer_guides/templates/casting) section for specific details.
+instead, or if used in an actual XML file use `.CDATA` (see [template casting](/developer_guides/templates/casting)).
 
 #### Upgrade code that uses SQLQuery
 
-Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed.
-
-See the [3.2.0](3.2.0) upgrading notes for details on how existing code should be upgraded.
+Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed (check the [3.2.0](3.2.0) upgrading notes).
 
 #### New asset storage mechanism
 
@@ -215,7 +210,7 @@ Note that this will not allow you to utilise certain file versioning features in
 	  legacy_paths: true
 
 
-See [/developer_guides/files/file_management] for more information on how the new system works.
+See our ["File Management" guide](/developer_guides/files/file_management) for more information.
 
 #### Migrating File DataObject from 3.x to 4.0
 
@@ -301,7 +296,6 @@ existed in the assets folder, and that the Filename of the DataObject was set to
 Since the storage of physical files is no longer a standard location, it's necessary to delegate the writing of such
 files to the asset persistence layer. As a wrapper for an individual file, you can use any of the `setFrom*`
 methods to assign content from a local (e.g. temporary) file, a stream, or a string of content.
-
 You would need to upgrade your code as below.
 
 Before:
@@ -357,7 +351,6 @@ which are used to generate what are now called "variants" of assets, is now a ge
 and `DBFile` classes through this trait.
 
 Custom manipulations, applied via extensions, must be modified to use the new API.
-
 For instance, code which sizes images to a fixed width should be updated as below:
 
 Before:
@@ -378,9 +371,7 @@ Before:
 	Image::add_extension('MyImageExtension');
 
 
-Now image manipulations are implemented with a single method via a callback generator.
-
-After:
+Now image manipulations are implemented with a single method via a callback generator:
 
 
 	:::php
@@ -444,8 +435,7 @@ These methods have been updated to include base fields (such as ID, ClassName, C
 well as composite DB fields.
 
 `DataObject::database_fields` does not have a second parameter anymore, and can be called directly on an object
-or class. E.g. `Member::database_fields()`
-
+or class. E.g. `Member::database_fields()`.
 If user code requires the list of fields excluding base fields, then use custom_database_fields instead, or
 make sure to call `unset($fields['ID']);` if this field should be excluded.
 
@@ -481,7 +471,7 @@ the `table_name` config can be applied to any DataObject class.
 
 
 In order to ensure you are using the correct table for any class a new [api:DataObjectSchema] service
-is available to manage these mappings.
+is available to manage these mappings (see [versioned documentation](/developer_guides/model/data_model_and_orm)).
 
 
 	:::php
@@ -494,15 +484,11 @@ is available to manage these mappings.
 	}
 
 
-See [versioned documentation](/developer_guides/model/data_model_and_orm) for more information.
-
 #### Upgrade implementations of augmentSQL
 
 Since this method now takes a `SQLSelect` as a first parameter, existing code referencing the deprecated `SQLQuery`
 type will raise a PHP error.
 
-E.g.
-
 Before:
 
 	:::php
@@ -547,8 +533,6 @@ In case that user code must customise this filename, such as for extensions whic
 for any error page, the extension point `updateErrorFilename` can be used. This extension point should
 also be used to replace any `alternateFilepathForErrorcode` used.
 
-E.g.
-
 
 	:::php
 	class MyErrorPageExtension extends SiteTreeExtension {
@@ -583,7 +567,7 @@ configuration customisation is done via overriding these templates.
 
 If upgrading from an existing installation, make sure to invoke `?flush=all` at least once.
 
-See [/developer_guides/files/file_security] for more information.
+See our ["File Security" guide](/developer_guides/files/file_security) for more information.
 
 #### `ListboxField` is now multiple-only
 
@@ -650,8 +634,6 @@ Rather than declaring the list of stages a model has, the constructor for `Versi
 parameter, which declares whether or not the model is versioned and has a draft and live stage, or alternatively
 if it only has versioning without staging.
 
-For instance:
-
 
 	:::php
 	/**
@@ -696,7 +678,6 @@ By default all versioned dataobjects will automatically publish objects that the
 
 ChangeSet objects have been added, which allow groups of objects to be published in
 a single atomic transaction.
-
 This API will utilise the ownership API to ensure that changes to any object include
 all necessary changes to owners or owned entities within the same changeset.
 
@@ -718,7 +699,7 @@ This means that for the most part, code that worked in 3.0 won't need to be chan
 
 An exception to this is any classes which once had the `SS_` prefix, which will now be instead prefixed with `DB`, and have an un-aliased prefix. For example `SS_Datetime` is now `DBDateTime`, and has the alias `DateTime` which may be used in config.
 
-For example:
+Before:
 
 	class MyObject extends DataObject {
 	    private static $db = array(
@@ -735,7 +716,7 @@ For example:
 	    }
 	}
 
-Will become:
+After:
 
 	use SilverStripe\ORM\FieldType\DBVarchar;
 
@@ -768,7 +749,6 @@ In case you want to keep using RestfulService, you can use `Firesphere/silverstr
 #### Upgrading from deprecated Oembed
 
 Instead of Oembed, the framework now relies on [oscarotero/Embed](https://github.com/oscarotero/Embed) to handle getting the shortcode-data for embedding. 
-
 If you have custom embedding-code relying on Oembed, please refer to the documentation provided by oscarotero.
 
 #### Admin URL can now be configured via custom Director routing rule