Improve readme

README.md

@@ -9,7 +9,11 @@ A versioning scheme that uses only major and minor version numbers.
 
 ## Features
 
-Based on [SemanticVersion] from the standard library it is comparable with and convertible to [SemanticVersion] and has an optional extension that adds convenience functionality to [SemanticVersion].  Last, it has a converter for easy use with [JSON::Serializable].
+Based on [SemanticVersion] from the standard library and is comparable with and convertible to `SemanticVersion`.  Includes a [SemanticVersion Extension] that adds convenience functionality to `SemanticVersion`. and a [ShortVersionConverter] for use with [JSON::Serializable].
+
+## Documentation
+
+* [Library API]
 
 ## Installation
 
@@ -31,7 +35,7 @@ Require the library.
 require "short_version"
 ```
 
-Create a [ShortVersion].
+Create a `ShortVersion`.
 
 ```crystal
 ShortVersion.new(1, 1)
@@ -52,7 +56,7 @@ ShortVersion.parse(semver)
 # => ShortVersion(@major=1, @minor=1)
 ```
 
-Convert [ShortVersion] to [SemanticVersion]. **Note**: By default patch version is `0` unless otherwise specified.
+Convert `ShortVersion` to `SemanticVersion`. **Note**: By default patch version is `0` unless otherwise specified.
 
 ```crystal
 shortver = ShortVersion.parse("1.1")
@@ -64,15 +68,15 @@ shortver.to_semver(1) # Specify patch version
 # => SemanticVersion(@major=1, @minor=1, @patch=1, ...)
 ```
 
-Compare [ShortVersion] <=> [ShortVersion].
+Compare `ShortVersion` <=> `ShortVersion`.
 
 ```crystal
 ShortVersion.parse("1.2") < ShortVersion.parse("1.3") # => true
 ShortVersion.parse("1.2") == ShortVersion.parse("1.2") # => true
 ShortVersion.parse("1.2") > ShortVersion.parse("1.1") # => true
 ```
 
-Compare [ShortVersion] <=> [SemanticVersion].
+Compare `ShortVersion` <=> `SemanticVersion`.
 
 ```crystal
 ShortVersion.parse("1.2") < SemanticVersion.parse("1.3.0") # => true
@@ -82,15 +86,15 @@ ShortVersion.parse("1.2") > SemanticVersion.parse("1.1.19") # => true
 
 ### ShortVersionConverter (Optional)
 
-Converter to be used with [JSON::Serializable]  to serialize a [ShortVersion].
+Converter to be used with [JSON::Serializable]  to serialize a `ShortVersion`.
 
 Require the converter.
 
 ```crystal
 require "short_version/converter"
 ```
 
-Convert a [SemanticVersion] to [ShortVersion].
+Convert a `SemanticVersion` to `ShortVersion`.
 
 Add the converter to the JSON::Field decorator.
 
@@ -106,14 +110,14 @@ struct Example
 end
 ```
 
-Parse json string and convert to [ShortVersion].
+Parse json string and convert to `ShortVersion`.
 
 ```crystal
 example = Example.from_json("{\"short_version\":\"1.2\"}")
 example.short_version # => ShortVersion(@major=1, @minor=2)
 ```
 
-Convert [ShortVersion] to json string.
+Convert `ShortVersion` to json string.
 
 ```crystal
 shortver = ShortVersion.parse("1.0")
@@ -125,15 +129,15 @@ example.to_json # => "{\"short_version\":\"1.0\"}"
 
 Extending SemanticVersion is unnecessary but it adds some nice conveniences and may allow your code to flow more naturally.
 
-**Note**: It extends the [SemanticVersion] Struct from the standard library by adding a `to_shortver` instance method and `Comparable(ShortVersion)` functionality.
+**Note**: It extends the `SemanticVersion` Struct from the standard library by adding a `to_shortver` instance method and `Comparable(ShortVersion)` functionality.
 
 Require the extension.
 
 ```crystal
 require "short_version/extensions/semantic_version"
 ```
 
-Convert a [SemanticVersion] to [ShortVersion].
+Convert a `SemanticVersion` to `ShortVersion`.
 
 ```crystal
 semver = SemanticVersion.parse("1.2.3")
@@ -143,7 +147,7 @@ semver.to_shortver # => ShortVersion(@major=1, @minor=2)
 ShortVersion.parse(semver) # => ShortVersion(@major=1, @minor=2)
 ```
 
-[SemanticVersion] parse [ShortVersion].
+`SemanticVersion` parse `ShortVersion`.
 
 ```crystal
 shortver = ShortVersion.new(1, 2)
@@ -154,7 +158,7 @@ semver # => SemanticVersion(@major=1, @minor=2, @patch=0, ...)
 ShortVersion.parse(semver) # => ShortVersion(@major=1, @minor=2)
 ```
 
-Compare [SemanticVersion] <=> [ShortVersion].
+Compare `SemanticVersion` <=> `ShortVersion`.
 
 ```crystal
 SemanticVersion.parse("1.2.3") < ShortVersion.parse("1.3") # => true
@@ -193,6 +197,9 @@ And that's it, a release is created.
 
 - [Mario Affonso](https://github.com/mraffonso) - creator and maintainer
 
-[ShortVersion]: https://mraffonso.github.io/short_version/ShortVersion.html
-[SemanticVersion]: https://crystal-lang.org/api/SemanticVersion.html
 [JSON::Serializable]: https://crystal-lang.org/api/JSON/Serializable.html
+[Library API]: https://mraffonso.github.io/short_version/ShortVersion.html
+`SemanticVersion`: https://crystal-lang.org/api/SemanticVersion.html
+[SemanticVersion Extension]: https://mraffonso.github.io/short_version/SemanticVersion.html
+[ShortVersionConverter]: https://mraffonso.github.io/short_version/ShortVersionConverter.html
+