New design for tables

[jenniferfell]

I'm submitting a...

[ ] Regression (a behavior that used to work and stopped working in a new release)
[ ] Bug report  
[ ] Performance issue
[ ] Feature request
[ X] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead see https://github.com/angular/angular/blob/master/CONTRIBUTING.md#question
[X ] Other... Please describe: AIO css and table generation

Current behavior

Currently, there are two table designs. One for HTML tables, and one for markdown tables. We need to standardize on one marked convention, and it's time to refresh the look and feel as well.

Expected behavior

The general look and feel of tables could use a refresh and optimization for data-rich tables. It would be nice to align the look-and feel more with the Google dev doc style guide: https://developers.google.com/style/tables

Some specifics:

• Title row should use sentence caps to be more consistent with our other headings and with Google dev doc style guide (linked above)

• Title row should stand out without dominating over the page's section headings. The current bold titles in the HTML tables seem too strong.

• Content in rows should be top aligned, so the first line of text in each row is aligned. This improves readability by improving line scanning left to right, and it makes the table easier to use when scrolling (users see something in each cell at the same time, rather than the blanks that can appear when middle-aligning text).

• Less vertical padding within table rows, to better accommodate data-rich tables with less scrolling

• HTML tables currently have vertical border between columns in the title row, but the rows below do not have the vertical border. Standardize one way or the other.

Keep:

• Outer border and horizontal rule between rows seems to be working well in all tables right now

Minimal reproduction of the problem with instructions

https://angular.io/guide/docs-style-guide#tables
https://angular.io/guide/releases currently has both markdown and html tables in it

APIs also use tables without heading rows:
https://angular.io/api/animations

What is the motivation / use case for changing the behavior?

Nicer look and feel. Easier use (read and scan) of tables. Re-standardize on one markup convention.

Environment

Angular version: X.Y.Z


Browser:
- [ ] Chrome (desktop) version XX
- [ ] Chrome (Android) version XX
- [ ] Chrome (iOS) version XX
- [ ] Firefox version XX
- [ ] Safari (desktop) version XX
- [ ] Safari (iOS) version XX
- [ ] IE version XX
- [ ] Edge version XX
 
For Tooling issues:
- Node version: XX  
- Platform:  

Others:

[jenniferfell]

Snapshot of tables as they are today

[jenniferfell]

@sjtrimble FYI. @IgorMinar and I talked about doing this in Q4.

[jenniferfell]

(Jira DOCS-388)

[jenniferfell]

Replaces #23980

[jenniferfell]

More requirements:

• ALL CAPS should not be used as column headings. Not only does it not match Google Dev Doc Style (mentioned above), but it's harder for readers to scan than Title Caps or Sentence caps. (Readers scan letters by their shapes. in ALL CAPS, all letters have the same basic shape, a rectangle. Similarly, all words have the same shape, a rectangle. For faster scanning and greater comprehension, mixed caps are essential.)

• Contents of heading row cells and other row cells must align the same way. Currently, heading row aligns to center, while other rows align left. This results in an odd effect where titles aren't above the content below them in the column. This cannot be overridden in the markdown source today.

[jenniferfell]

Places with tables (sampling):

• API reference
  • https://angular.io/api/common/CurrencyPipe
• CLI command reference
• https://angular.io/guide/cheatsheet
• https://angular.io/guide/ajs-quick-reference
• https://angular.io/guide/releases
• https://angular.io/guide/file-structure
• https://angular.io/guide/browser-support
• https://angular.io/guide/frequent-ngmodules
• https://angular.io/guide/ngmodule-api
• https://angular.io/guide/module-types
• https://angular.io/guide/comparing-observables

[jenniferfell]

Add to requirements - author control:

• Ability for authors to control width of table
• Ability for authors to control width of columns
• Ability to have a table cell with >1 paragraph or a bullet list in it

[jenniferfell]

Top priority in mtg today:
Add to requirements - general:

• Responsiveness, esp wide tables in API reference and cheat sheet

[jenniferfell]

Markdown can be used for tables that meet these criteria:

• Simple structure. No more than 2-3 columns.
• Simple content. Cell content has no more than 1 sentence or a short paragraph.
• No spanning of cells (which isn't accessible any way).
• No need for author to control table or column width.
  Use HTML for complex tables that don't meet that criteria.

[gkalpak]

Another issue about tables:

• Empty spaces in Extra Options router properties docs #27296: Too long values in one cell make the whole column too wide (often pushing the rest of the columns off the viewport).

[jenniferfell]

• Need ability to control column width, at least by percentage. This will reduce the impact of one cell having a long value. Instead, the author can optimize the table layout for most of the data, and force that one cell to wrap the text.

• Need cleaner style with less extra white space as padding. Technical content in tables isn't like marketing content. It's content-rich, and needs to be. Quite often we have to take something that should be column 1 of a single table and instead break it into multiple tables each in their own section. We've also had to take something that should be 3 columns and instead combine 2 columns and just use a line break or paragraph break to separate the different content in each cell in column 2 (see many API reference pages).

Another example where the layout and fonts are a bit "off" with the current table design: https://next.angular.io/guide/deprecations

Example where we wanted a 3rd column for "default" but had to merge it into column 2 because without tuning column %s the layout wasn't usable: https://next.angular.io/cli/build

[atscott]

Closing as not a priority at this time. Thanks for the thorough and helpful feedback!

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}