Added basic documentation

README.md

@@ -2,13 +2,79 @@
 
 # schemadocs - the Giant Swarm JSON Schema docs generator 
 
-- Generates Markdown documentation from JSON schema files and injects it into text files
-- Validates generated Markdown documentation in text files and checks whether it is aligned with the supplied JSON schema file
+schemadocs helps you generate documentation from your JSON schema and store it in README and other documentation files
+
+## Features
+
+- Generate Markdown documentation from a JSON schema file and inject it into an output text file
+- Validate generated Markdown documentation in a text file and check whether it is aligned with documentation generated from the supplied JSON schema file
+
+## Installation
+
+```nohighlight
+go install github.com/giantswarm/schemadocs@latest
+```
 
 ## Usage
 
+### Generating documentation
+
+Executing `schemadocs generate` without any options will generate Markdown documentation from a JSON schema file and store it in a `README.md` file in the current working directory. 
+
+It is required that the README file contains exactly one pair of placeholder strings, which mark the start and end of the documentation. 
+By default, the placeholders are `{::comment} # DOCS_START {/:comment}` and `{::comment} # DOCS_END {/:comment}`.
+
+If the README file does not exist or in case it does not contain one pair of valid placeholder strings, the execution will fail.
+
+```nohighlight
+$ schemadocs generate schema.json
+
+Generating documentation
+Schema: schema.json
+Destination file: README.md
+Using default placeholders '{::comment} # DOCS_START {:/comment}' and '{::comment} # DOCS_END {:/comment}'
+
+[SUCCESS] Documentation generated successfully!
+```
+
+To generate the documentation to a custom file, apply the `--output-path` option.
+To use a pair of custom placeholder strings, apply the `--doc-placeholder-start` and `--doc-placeholder-end`.
+
 ```nohighlight
-schemadoc generate path/to/myschema.json
+$ schemadocs generate schema.json --output-path README.md --doc-placeholder-start [DOCS_START] --doc-placeholder-end [DOCS_END]
+```
+
+**Note:** The `--doc-placeholder-start` and `--doc-placeholder-end` need to be provided as a pair. So, if one of them is specified, the other one needs to be specified, too.
+
+Use `--help` to learn about more options.
+
+### Validation
+
+Validate documentation a text file by comparing it to documentation generated from a JSON schema file specified in the required `--schema` option.
+The validation passes in case both documentations match exactly.
+
+It is required that the text file contains exactly one pair of placeholder strings, which mark the start and end of the documentation.
+By default, the placeholders are `{::comment} # DOCS_START {/:comment}` and `{::comment} # DOCS_END {/:comment}`.
+
+If the text file or the schema file do not exist or in case the text file does not contain one pair of valid placeholder strings, the execution will fail.
+
+```nohighlight
+$ schemadocs validate README.md --schema schema.json
+
+Validating documentation
+Source file: README.md
+Schema file: schema.json
+Using default placeholders '{::comment} # DOCS_START {:/comment}' and '{::comment} # DOCS_END {:/comment}'
+
+[SUCCESS] Documentation is valid!
+```
 
-schemadoc validata --schema path/to/myschema.json path/to/text-file.md
+To use a pair of custom placeholder strings, apply the `--doc-placeholder-start` and `--doc-placeholder-end`.
+
+```nohighlight
+$ schemadocs validate README.md --schema schema.json --doc-placeholder-start [DOCS_START] --doc-placeholder-end [DOCS_END]
 ```
+
+**Note:** The `--doc-placeholder-start` and `--doc-placeholder-end` need to be provided as a pair. So, if one of them is specified, the other one needs to be specified, too.
+
+Use `--help` to learn about more options.