AS2-Vocab: Replace tables with description lists

[trwnh]

Tables are not responsive and render very poorly across screen sizes without enough width and height. Description lists are easier to view and also more semantically correct. CSS can be used to render a grid layout when there is enough space on larger screens.

The current document is rather egregious and will horizontally scroll on anything less than 1781px wide.

[TallTed]

It would be a lot easier to know what you're complaining about if you included a link to the live editor's draft. That said --

The current document is rather egregious and will horizontally scroll on anything less than 1781px wide.

Any table (or other content) that requires a viewport of 1781px needs some attention to its markup and CSS. I'm working on a 15" MBP for which the WebDeveloper extension reports Viewport: 1407px x 992px, so I'm going to need to scroll horizontally. That's just poor form!

Semantic tags can be added to tables to make them "more semantically correct".

Tables are often easier to view, even on smaller screens, if the CSS is written to suit and the markup is well done.

They absolutely can be responsive, if they're not set with fixed widths in pixels, but rather are set with varying widths in percentages.

Whether these changes are sufficient for any given table or data depends a lot on the number of columns and how wide each needs to be to contain the longest "word" without wrapping it. Without seeing exactly what you're talking about I cannot be certain, I remain confident that some smaller changes to the markup are likely to resolve your complaints.

[trwnh]

I mean the actual spec at https://www.w3.org/TR/activitystreams-vocabulary/ is too wide.

This is at the widest it can be before the sidebar expands (1247px):

This is the minimum width to get everything mostly visible, although there's still horizontal scrolling (1688px):

That horizontal scroll is because the table for Activity types is even wider! (the aforementioned 1781px)

Semantically, <table> is supposed to represent a table, not to be used for layout. But it's doubly bad when the layout suffers for it, too. It's wild that you basically need to fullscreen your browser window on a 1920x1080 monitor just to read the tables. Putting the spec side-by-side with anything else is a bad UX. Putting the spec on a 1200px wide vertical monitor is also a bad UX.

I feel like we could learn something from the Security Vocabulary at https://w3id.org/security/ -- although even that has some CSS issues that make reading it feel cramped on, say, a smartphone. Ironically, the browser default styling for <dl> doesn't have those issues; it's entirely caused by the CSS on that page forcing the <dt> and <dd> to be in a row instead of stacked as they normally are.

A better example

Object

Comment

Describes an object of any kind

Properties

attachment

attributedTo

audience

{
  "type": "Object"
}

Example 1: A simple object

[TallTed]

Ah, OK, now your complaint makes more sense. I think that just treating the now-distinct column of Examples as continuations of the Description would make a big difference. Perhaps not sufficient.

I'd like to give your "better example" proper consideration, but I don't think that's possible with a partial example. It should have all the data seen above in the tabular markup.

[trwnh]

It would look different in ReSpec than in GitHub comments, so I wrote a minimal example just to get an impression across. Imagine the same thing, but longer (i.e. with more dt-dd groups).

Also, in ReSpec you could make the properties use CSS Flexbox instead of being a stack, to save space more similarly to the current spec document's appearance.

[evanp]

I think this makes a tonne of sense and would greatly improve the readability of the document. I tried to do some improvements in the miscellany docs, but we may just want to reorganize entirely.

A good note, thanks!