Open adorilson opened 7 months ago
Screenshots:
- table, for example, in User defined functions
- list, for example, in Modules
- in line, for example, in Code Objects
It must be standardized. But what will be the choice? In line is the worst. It is not a choice. But about table or list?
Standardising can help, although I wouldn't say it must be done, but we should pick the best tool to present the information in each case. I agree the inline ones need changing (Google calls these "embedded" or "run-in" lists and recommends transforming into bulleted or numbered lists: https://developers.google.com/tech-writing/one/lists-and-tables).
For accessibility, this 2012 article recommends tables over definition lists (which is what example 2 is): https://snook.ca/archives/html_and_css/definition-lists-v-tables
However, this 2022 post says support for definition lists is generally good, and this 2017 says tables are OK too:
So let's compare what info is being conveyed in these three examples.
The table of "special attributes" has three columns:
The definition list has "predefined (writable) attributes":
Followed by a single "special read-only attribute":
These could be combined into a single table, but I'm not entirely clear on the difference between "predefined (writable)" and "special read-only".
Finally, the inline descriptions are all "special read-only attributes":
I guess a definition list would suffice for those with just two headers, although tables are a more compact, and it's a problem that this page is already so long.
What do you think?
If we go for tables, I suggest using list-table
markup, it makes things easier to edit in the future than adjusting whitespace in grid tables:
Thanks for the deep analysis, @hugovk .
In this case, I think a table is more suitable. Concerning "predefined", "special only" and other field details, I think a "Notes" column can be used for this, as already done in some cases.
Would you like to put together a PR? Feel free to do them one at a time, if it's easier.
At some moment in the future, I can do that. However, if somebody more available wants to do this, go ahead.
Documentation
Object attributes are listed several times in the Data Model section. However, there is no standard format. It was used:
It must be standardized. But what will be the choice? In line is the worst. It is not a choice. But about table or list?
Linked PRs