search

grafana / writers-toolkit

Technical documentation guidelines for Grafana Labs documentation
https://grafana.com/docs/writers-toolkit/
16 stars 12 forks source link

Determine if a table section is needed in the toolkit #773

Open imatwawana opened 6 days ago

imatwawana commented 6 days ago

Tables have come up in the style roundtable and the perception is that we need a table section. We should check first if Google's developer guide covers the guidance we need.

jdbaldry commented 5 days ago

https://developers.google.com/style/tables

One thing I spotted is that we should discourage the use of <br> elements and instead use <p> elements to have paragraphs in our tables which makes sense.

jdbaldry commented 5 days ago

In https://developers.google.com/style/ui-elements, they use the same formatting rules within the table cells as outside. Namely, that bold is used to highlight UI elements.

jdbaldry commented 5 days ago

https://github.com/grafana/writers-toolkit/pull/772/files#diff-dce4785db28c782d8c85d67948ddaed3a01acc26b986f31c08fc02e666f9294fR296 makes sense because it can be confusing visually (Is it a table heading or a UI element). I don't think Markdown helps us here because I don't see how it would allow us to inform Hugo to markup a column as a heading column.