Repository navigation
Inconsistent format to list attributes in Data Model section #111746
Description
Documentation
Object attributes are listed several times in the Data Model section. However, there is no standard format.
It was used:
- 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?
Activity
hugovk commented on Nov 5, 2023
Screenshots:
TableStandardising 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:
adorilson commented on Nov 19, 2023
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.
hugovk commented on Nov 20, 2023
Would you like to put together a PR? Feel free to do them one at a time, if it's easier.
adorilson commented on Nov 23, 2023
At some moment in the future, I can do that. However, if somebody more available wants to do this, go ahead.