Few improvements to metadata docs
# Metadata and Userdata handling
-Most providers offer a mechanism to provide a OS with some additional
-metadata as well as custom userdata. `Metadata` in this context is
-fixed information provided by the provider (e.g. the host
-name). `Userdata` is completely custom data which a user can supply to
-the instance.
+Most providers offer two general mechanisms to provide compute instances
+with information about the instance that cannot be discovered by any other
+means. There are usually two types of information, namely _metadata_ and
+_user-data_. Metadata is usually set by the provider (e.g. geographical
+region of the datacentre, name given to the instance, external IP address,
+tags and other similar information), while userdata is fully custom,
+hence the name, and it is the information that user may supply to their
+instances before launch (it is immutable in most providers).
The [metadata package](../pkg/metadata/) handles both metadata and
-userdata for a number of providers (see below). It abstracts over the
-provider differences by exposing both metadata and userdata in a
-directory hierarchy under `/var/config`. For example, sshd config
+userdata for a number of providers (see below). It abstracts over
+the provider differences by exposing both metadata and userdata in
+a directory hierarchy under `/var/config`. For example, sshd config
files from the metadata are placed under `/var/config/ssh`.
Userdata is assumed to be a single string and the contents will be
-stored under `/var/config/userdata`. If userdata is a json file, the
+stored under `/var/config/userdata`. If userdata is a JSON file, the
contents will be further processed, where different keys cause
-directories to be created and the directories are populated with files. Foer example, the following userdata file:
-```
+directories to be created and the directories are populated with files.
+For example, the following userdata file:
+```JSON
{
"ssh" : {
"sshd_config" : {
@@ -66,5 +70,6 @@ GCP userdata is extracted from `/computeMetadata/v1/instance/attributes/userdata
## HyperKit
-HyperKit does not support metadata and userdata is passed in as a single file via a ISO9660 image.
-
+HyperKit does not distiguish metadata and userdata, it's simply
+refered to as data, which is passed to the VM as a disk image
+in ISO9660 format.
