From fd02d9bd6b80d2be8d1cd105a599555d05b748c6 Mon Sep 17 00:00:00 2001
From: George Steel <george@net-glue.co.uk>
Date: Tue, 17 Oct 2023 16:19:17 +0100
Subject: [PATCH] docs: Improve document outline and structure

Signed-off-by: George Steel <george@net-glue.co.uk>
---
 docs/book/v2/migration/preparing-for-v3.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/book/v2/migration/preparing-for-v3.md b/docs/book/v2/migration/preparing-for-v3.md
index 74170fe7b..6787e769c 100644
--- a/docs/book/v2/migration/preparing-for-v3.md
+++ b/docs/book/v2/migration/preparing-for-v3.md
@@ -2,7 +2,9 @@
 
 Version 3 will introduce a number of backwards incompatible changes. This document is intended to help you prepare for these changes.
 
-## Template Resolvers
+## Signature Changes
+
+### Template Resolvers
 
 In version 2, template resolvers, which all implement the method `ResolverInterface::resolve()` have varying return types along with some undocumented or inconsistent behaviour, specifically concerned with error handling, for example, when a template cannot be found, or no templates have been configured.
 
@@ -18,9 +20,9 @@ return $this->resolver->resolve($name, $this->renderer);
 
 #### After
 
-If the template resolvers is used as standalone, use a `try`-`catch` block to create a custom signal for a missing template in an application:
+If a template resolver is used as standalone, use a `try`-`catch` block to create a custom signal for a missing template in an application:
 
-```
+```php
 try {
     return $this->resolver->resolve($name, $this->renderer);
 } catch (\Laminas\View\Exception\ExceptionInterface $error) {
@@ -28,7 +30,9 @@ try {
 }
 ```
 
-### Deprecations of undocumented behaviour
+## Deprecations 
+
+### Undocumented Behaviour
 
 `\Laminas\View\Resolver\TemplateMapResolver` allows runtime mutation of the template map with the `add($name, $path)` method.
 This method has an undocumented feature where passing `null` to the `$path` parameter allows removal of an existing template providing that `$name` is a string. This feature is deprecated and will now issue an `E_USER_DEPRECATED` runtime error if used in this way.