Summary

Introduce a concept into the ECS repo which captures extended usage examples. These examples would appear in the ECS documentation as a dedicated page per field set.

Motivation:

Real-world examples are powerful tools to help users better grasp ECS concepts and how users can better map their custom data sources. In addition to the field specifications, ECS also provides guidance on the preferred design patterns for modeling particular events.

A wealth of examples and past discussion is captured in the repo and on Discuss, but not in the ECS docs. Having such examples incorporated into the docs would provide a single, authoritative location. Restructuring could also allow us to include diagrams, code snippets, and other visual aids.

Issues touching on or providing such examples:

• Is ECS confusing to you? #516
• Add ECS categorization examples #860
• [ECS] Multiple users in an event proposal #809
• Populating of source/destination if both source/client or server/destination is being used #300

Design Proposal:

• Refactor the existing schemas directory

  • As of ECS 1.5.0, the schemas directory contains a collection of YAML files and a README.
  • create subdirectories named after the fieldset
  • Each subdirectory contains the schema file for that fieldset. It can also contain an AsciiDoc formatted usage or example file.

• Add a new page dedicated to the free-form usage and examples docs. The page will be nested underneath the field set reference page.

• The AsciiDoc generator will be updated to support this refactoring in the docs

To-do:

• Add discrete attribute to field details page headers #989 Add [discrete] attribution for field details section headers.
  • [discrete] will need to be added to the previous ECS version branches to ensure the legacy formatting is retained after changing the chunking level.
• Change ECS chunking level docs#1970 docs PR to increase chunking level for ECS book from 1 to 2
• Add usage docs section #988 add free-form usage asciidoc per fieldset