@jen-huang @hbharding Here is an example on how the above table looks in Kibana. Compared to your design, I used 3 instead of 2 columns as I think we will need 3. The bigger problem is the length of each column, especially the first one.

@mostlyjason @dedemorton @bmorelli25 We need to come up with a recommended structure for the README files like the one above. It would be great if someone could take all the docs from a module and come up with the "perfect" doc page which we then can take as an example. This should also make discussions easier.

Note: Commenting it on this PR as it already shows quite a bit of content but lets not have all the follow up discussions here but a separate place.

@mtojek I expect the other discussions will not affect this PR so I already merged it. Will open separate issue for the generation of fields.

@ruflin Yes, we can help you come up with a doc page layout. I've created an issue to track the work on our end.

@neptunian Can you advise on @ruflin's questions above re: table column width, and collapsible content?

@ruflin @jen-huang In regards to to table column widths, we are using the table-layout: auto because we don't know what widths we want the columns to be. The EUI style breaks table cells with long words. If it didn't then that would be potentially very wide cell and make another column very tiny. I'm not sure there is much we can do here but we can ask EUI's advice. @hbharding and I were not able to come up with a workaround at the time.

react-markdown does not seem to provide a renderer for details/summary markdown, so we couldn't target it to wrap it in something, but since the markdown itself for this is just HTML it will be rendered as such and styled:

You can try it here https://rexxars.github.io/react-markdown/

@neptunian Does this mean we can use "all" html in our markdown?

For the table: I think we need to come up with a way to visualise this data. It does not have to be a table but at least nicer than what we have today: https://www.elastic.co/guide/en/beats/filebeat/current/exported-fields-nginx.html

@ruflin No, that was incorrect what I wrote. By default it escapes HTML otherwise there would be a security issue with actually parsing and rendering any HTML unless we are sure it can be trusted. So the summary/details will not work and isn't supported by this component unless we want to parse html.

For the table: I think we need to come up with a way to visualise this data. It does not have to be a table but at least nicer than what we have today

@ruflin I totally agree. I really dislike the definition list format in our reference documentation. It's hard to scan and looks bad. Tables are much better, but long field names don't render well in columns and cause problems with our page layout (right-hand nav).

We really need to do better for any text that is displayed in Kibana. The text needs to be clear and concise so users can scan it quickly. (Docs should be that way, too, but users are more tolerant of wordy reference docs.)

I have a couple of different ideas about how we make the text easier to read:

• Provide the namespace up front and simply use the field name in the table. So instead of nginx.access.remote_ip_list, the table would show remote_ip_list.

• Instead of showing field descriptions, provide the description in a popup. This would only work if we think the field names are descriptive enough and that most users won't need to see the description. If the descriptions are critical, we should not hide them.

@dedemorton Unfortunately ECS breaks the "provide namespace upfront" idea I think. Nginx is a good example. 95% of the fields are ECS fields and don't have the nginx prefix, only a few have it.

I like the description pop up idea.

Just remember that popup are really annoying for mobile users (it's easy to miss a show/hide section and it's not possible for perform a "hover" action).

Hey there. I have a few ideas that may help:

1. Use the compressed from of EuiTable. This will reduce the font size and spacing, which will help with line wrapping and reduce the overall height of the table (less scrolling).
2. Use different text styles for the columns. This will make the table easier to scan. The columns should appear in this order:
   • "Field" is bold
   • "Type" is inline-code
   • "Description" is regular text. It should be the last column since it can be the longest and wrap the most
3. I like @dedemorton's idea of removing the namespace and showing it above the table as a header. So nginx.access.remote_ip_list becomes <h5>nginx.access.*</h5> and <td><strong>remote_ip_list</strong></td>. Nicolas could you provide a link or example to an ECS version
4. Set a fixed width of the first column. I'd prefer if the content could dictate the size, so I don't love this idea.

As for the pop up / tooltip idea, I'm not a fan. For someone who cares to read the descriptions (which I presume many will, even if it's a quick scan or a command+F search), it will be painfully slow to hover on a small icon and wait for the transition delay for the tooltip to appear.

Here's a screenshot of the EUI docs, which uses the compressed table style:

Here an example of the nginx.access fields (subset):

@timestamp
source.address
source.ip
user.name
url.original
http.version
message
user_agent.original
...
nginx.access.remote_ip_list

As you see, there is only 1 field in nginx.access with the actual prefix, all others are ECS fields.

@hbharding We tried the compressed style and there is still the same problem. It might solve a few cases but it doesn't solve them all or possibly most. For setting a fixed width, you're thinking to use some number for all of them like 300px? It would still not solve for all cases and there would be too much room in some cases and possibly make something like the description column unnecessarily small. One thing we can do is not let these namespaces break and then use an ellipsis + max-width? When you hover over it, the alt tag shows the full name. Or if in mobile you have click on it to show the full name. Similar to the popup idea except it restricts the width of the namespace column. I think we need to restrict the width in some way as we don't know how long it could be. Otherwise perhaps we should not use a table.

I made this PR elastic/kibana#61294 which helps a bit. There are ways we can make it look better, but it assumes that tables will only ever be used for showing exported fields. If we're okay with this assumption, i'd propose that the 1st column (field) is 33%, and the other columns are sized based on their contents. This could be problematic if a markdown author tried making a table with more than 3 columns.