Ecs: Redesign field details page

[ebeahan]

Summary:

Improve upon the field set page layout and user experience in the ECS field reference guide docs.

Motivation:

• Provide a well-organized, thorough, and accessible reference guide for the ECS field sets.
• Expand available space to provide thorough description of each field and any necessary examples specific to a field.

Resources:

• Public ECS Brainstorming Google Doc

Design Proposal:

• Refactor the field reference doc section

Continue to provide the table of fields within a fieldset, but include links to free-form text section that allow room for extended descriptions, code snippets, visuals, etc.

• Simple (and not final) mockup:

• The AsciiDoc generator will be updated to support this refactoring

[webmat]

Super excited about this!

The screenshot you've included seems to be about the full page redesign, rather than the plain text section per field set. Not sure if that was intentional?

I very much want these two things, the free form text section and the page redesign. However I think the work could be split in two. I've been envisioning the free form text as potentially a second page per field set, rather than a new section in the same page. If you think this makes sense, it would simplify splitting the work in two. WDYT?

[ebeahan]

Yes - Agree if we separate the pages the work should be split.

I had the two tasks separated initially. I have been leaning towards the single page approach (text section + page redesign simultaneously), but after compiling some thoughts (👇 ) this may the less appealing of the two. I certainly want to avoid introducing any confusion. 😅

---

Thoughts

Single page

• Incorporate any additional text or examples for each field underneath that field's section.
• Retain a single page per field set
• I don't see all field sets needing the second page (e.g. ecs.*). Always have one page containing all the details vs. some field sets having multiple pages.
• One larger effort to implement vs. two smaller ones

Separate pages

• Examples could be grouped by their use case vs. which field(s). I believe will be more clear for users.
• A separate page avoids any confusion over which field section an example resides under (example: we want to express the intended usage of source.address, and source.domain or source.ip, which field does that usage belong under under the single page design?).
• Having the second page per field set does provide more space for visuals, other tables, diagrams, code snippets etc.
• We can enjoy the plain text additions while we work the page redesign separately 😎

[webmat]

Yes the "free text" docs was always meant to be one (optional) big blob per field set, where we can have illustrations, talk about how fields in the field set relate to each other, and so on.

This will give us the ultimate flexibility in explaining each field set holistically, without being constrained by only having a paragraph per field available to us.

Having these as two distinct pages also has the advantage of keeping one page with the regular structure & constraints, and a companion page that is free form, but doesn't affect the structure of the other page.

[webmat]

We may want to manually sketch the nav on these optional pages, before spending too much time on code.

[ebeahan]

@webmat Sounds good :smile: . I agree we should have a rough mockup ~so~ to discuss before getting into the implementation too much.

I'll edit this issue to better reflect the page redesign, and open a second issue to focus on the free text page implementation.

[webmat]

Awesome, thanks for opening #943!

Perhaps also link to the public google doc brainstorm in the body of this issue?

[ebeahan]

Also noting we should have a direct link to each of the fields to quickly share with users.