Mat's review of static asciidoc files

Makefile

@@ -112,6 +112,9 @@ readme:
 	cat docs/about.md >> README.md
 	cat docs/generated-files.md >> README.md
 
+.PHONY: reload_docs
+reload_docs: generator docs
+
 # Download and setup tooling dependencies.
 .PHONY: setup
 setup: ve

docs/additional.asciidoc

@@ -0,0 +1,7 @@
+[[ecs-additional-information]]
+== Additional Information
+
+// include::use-cases.asciidoc[]
+include::faq.asciidoc[]
+include::glossary.asciidoc[]
+include::contributing.asciidoc[]

docs/contributing.asciidoc

@@ -1,8 +1,7 @@
 [[ecs-contributing]]
-== Contributing to {ecs}
+=== Contributing to {ecs}
 
 All information related to ECS is versioned in the https://github.com/elastic/ecs[elastic/ecs] repository. All
 changes to ECS happen through Pull Requests submitted through Git.
 
 See the https://github.com/elastic/ecs/blob/master/CONTRIBUTING.md[Contribution Guidelines].
-

docs/converting.asciidoc

@@ -0,0 +1,46 @@
+[[ecs-converting]]
+=== Converting a Custom Implementation
+
+A common schema helps you correlate and use data from various sources.
+
+Fields for most Elastic modules and solutions (version 7.0 and later) are mapped
+to the Elastic Common Schema. You may want to map data from other
+implementations to ECS to help you correlate data across all of your products
+and solutions.
+
+Before you start a conversion, be sure that you understand the basics below.
+
+[float]
+[[core-or-ext]]
+==== Core and extended levels
+
+Make sure you understand the distinction between Core and Extended fields,
+as explained in the <<ecs-guidelines>>.
+
+[float]
+[[ecs-conv]]
+==== An approach to mapping an existing implementation
+
+Here's the recommended approach for converting an existing implementation to {ecs}.
+
+. Review each field in your original event and map it to the relevant ECS field.
+
+  - Start by mapping your field to the relevant ECS Core field.
+  - If a relevant ECS Core field does not exist, map your field to the relevant ECS Extended field.
+  - If no relevant ECS Extended field exists, consider keeping your field with its original details,
+    or possibly renaming it using ECS naming guidelines and attempt to map one
+    or more of your original event fields to it.
+
+. Review each ECS Core field, and attempt to populate it.
+
+  - Review your original event data again
+  - Consider populating the field based on additional meta-data such as static
+    information (e.g. add `event.type:syslog` even if syslog events don't mention this fact),
+    or information gathered from the environment (e.g. host information).
+
+. Review other extended fields from any field set you are already using, and
+  attempt to populate it as well.
+
+. Set `ecs.version` to the version of the schema you are conforming to. This will
+  allow you to upgrade your sources, pipelines and content (like dashboards)
+  smoothly in the future.

docs/faq.asciidoc

@@ -1,9 +1,9 @@
 [[ecs-faq]]
-== FAQ
+=== Questions and Answers
 
 [float]
 [[ecs-benefits]]
-=== What are the benefits of using ECS?
+==== What are the benefits of using ECS?
 
 The benefits to a user adopting these fields and names in their clusters are:
 
@@ -18,7 +18,7 @@ The benefits to a user adopting these fields and names in their clusters are:
 
 [float]
 [[conflict]]
-=== What if I have fields that conflict with ECS?
+==== What if I have fields that conflict with ECS?
 
 The
 {ref}/rename-processor.html[rename
@@ -30,34 +30,33 @@ field. If your field does not match ECS, you can rename your field to
 
 [float]
 [[addl-fields]]
-=== What if my events have additional fields?
+==== What if my events have additional fields?
 
 Events may contain fields in addition to ECS fields. These fields can follow the
 ECS naming and writing rules, but this is not a requirement.
 
 [float]
 [[dot-notation]]
-=== Why does ECS use a dot notation instead of an underline notation?
+==== Why does ECS use a dot notation instead of an underline notation?
 
 There are two common key formats for ingesting data into Elasticsearch:
 
 * Dot notation: `user.firstname: Nicolas`, `user.lastname: Ruflin`
 * Underline notation: `user_firstname: Nicolas`, `user_lastname: Ruflin`
 
-ECS uses the dot notation to represent nested objects. 
+ECS uses the dot notation to represent nested objects.
 
 [float]
 [[notation-diff]]
-==== What is the difference between the two notations?
+===== What is the difference between the two notations?
 
 Ingesting `user.firstname: Nicolas` and `user.lastname: Ruflin` is identical to ingesting the following JSON:
 
-```
-"user": {
-  "firstname": "Nicolas",
-  "lastname": "Ruflin"
-}
-```
+[source,json]
+    "user": {
+      "firstname": "Nicolas",
+      "lastname": "Ruflin"
+    }
 
 In Elasticsearch, `user` is represented as an {ref}/object.html[object
 datatype]. In the case of the underline notation, both are just
@@ -68,7 +67,7 @@ datatypes], which are arrays of objects.
 
 [float]
 [[dot-adv]]
-==== Advantages of dot notation
+===== Advantages of dot notation
 
 With dot notation, each prefix in Elasticsearch is an object. Each object can have
 {ref}/object.html#object-params[parameters]
@@ -87,7 +86,7 @@ modifying each part of the final event easier.
 
 [float]
 [[dot-disadv]]
-==== Disadvantage of dot notation
+===== Disadvantage of dot notation
 
 In Elasticsearch, each key can have only one type. For example, if `user` is an
 `object`, you can't use it as a `keyword` type in the same index, like `{"user":
@@ -96,9 +95,7 @@ the ECS data itself, this is not an issue because all fields are predefined.
 
 [float]
 [[underline]]
-==== What if I already use the underline notation?
+===== What if I already use the underline notation?
 
 As long as there are no conflicts, underline notation and ECS dot notation can
 coexist in the same document.
-
-