Currently the documentation about exported fields is not easy to read and scan due to problems with the layout. This proposal recommends improvements to the layout based on what I think should be done.

Problems with the existing layout:

• We use the same heading level for all headings, which makes the topic harder to scan and understand the relationship between sections.
• Definition list formatting makes the content longer (by about 40%) and therefore harder to scan.
• Redundant sections are not useful and make it look like there is a mistake. The logic in our generator creates these sections because of the filesets/metricsets used to collectd the data, but the sections don't really add value for the user.

Problems with the writing style/content:

• Inconsistent style (some full sentences, some fragments, erratic capitalization)
• Many descriptions lack depth and completeness. Some descriptions are missing. Users can't always tell how the fields get populated (do they enable a module? an input? define a processor?)

Proposal to address these issues:

• Use a different heading level for sub-sections. Avoid introducing additional heading levels beyond the title and sub-headings.
• Format the field reference info using tables instead of definition lists. Each table should have no more than 3 cols. When additional information is available (such as format, alias to, and required), include this information in the description. Why? Tables with more than 3 columns may result in formatting issues (text that overruns in the navigation) and are hard to read on smaller devices. Complex tables are also more difficult for people using screen readers.
• Edit the existing content for consistency and define style guidelines for new contributors to encourage consistency.
• Make sure the descriptions in each section indicate which modules/inputs/processors/etc populate the fields with data. This is useful for new users who aren't familiar with the available modules. If possible, there should be an active link back to the docs for the module that collects the data.

A prototype of the layout is available here: https://field-reference-test.firebaseapp.com/index.html Commented out because I accidentally blew this away.

The asciidoc I used is here: https://github.com/dedemorton/beats-docs-review/pull/2/files

Note that links are missing in this small test case. I've put everything into a single file to make it easy to build. The table layout I've chosen is relatively simple and easy to read as raw text in GitHub.

Some other stuff I played around with:

• Added descriptions to the overview page. I think this is better than a bulleted list that simply repeats the navigation.
• Removed repetition of "fields" in sub-headings. Does this work?
• Capitalized all headings.

Layout problems caused by our CSS or asciidoc (not easy to fix):

• Heading size and fonts do not play well together.
• Not enough cell padding between columns.
• No way to set the width of columns so that all tables on a page have the same column widths (this makes it easier to scan content quickly). Our docbook transform in our toolchain swallows column attributes.

Questions and open issues:

• Can we extract the descriptions defined in the Elastic Common Schema? Users should not have to look in more than one place to figure out the content and data type of a field.
• Can the script be modified to strip out redundant sections (sections that do not contain field descriptions)? Do these sections provide any real purpose, or are they just an artifact of how the current script logic works?
• Who will create the script?