diff --git a/README-DEV.md b/README-DEV.md
index cb2162e7f..35bd1ddc5 100644
--- a/README-DEV.md
+++ b/README-DEV.md
@@ -1,15 +1,15 @@
 # Notes for the SimpleSAMLphp SAML2 developer
 
-## Coding standard
+## Coding standards
 
 PSR-0, PSR-1 and PSR-12.
-Test with the PHPCS configuration in tools/phpcs/ruleset.xml
+Test with the PHPCS configuration in `tools/phpcs/ruleset.xml`
 (note if you have PHPStorm you can use this to turn on the PHPCS inspection).
 
 ## Testing
 
 Use PHPUnit for Unit Testing.
-Test with the 2 known users: (SimpleSAMLphp)[1] and (OpenConext-engineblock)[2].
+Test with the 2 known users: [SimpleSAMLphp][1] and [OpenConext-engineblock][2].
 
 ### Using Tests in Development
 
diff --git a/UPGRADING.md b/UPGRADING.md
index 3336cf0c3..c4916b90d 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -18,7 +18,7 @@ instead of the previous array
 
 ## 4.0 to 4.1
 
-** Assertion processor BC breaking change* *
+### Assertion processor BC breaking change
 
 The assertion processor in 4.0 assumed all assertions are encrypted and would try and decrypt twice, causing a fatal error.
 This problem was introduced in [#120](https://github.com/simplesamlphp/saml2/pull/120).
@@ -28,7 +28,7 @@ change, see: [97a7bd0](https://github.com/simplesamlphp/saml2/commit/97a7bd0be48
 
 ## 3.4 to 4.0
 
-** Assertion processor BC breaking change **
+### Assertion processor BC breaking changes
 
 The response processor in pre 4.0 releases assumed all assertions are decrypted, and caused a fatal error when the response was unsigned.
 This problem was fixed in [#120](https://github.com/simplesamlphp/saml2/pull/120).