What should an info-resource html page include?

dblodgett-usgs commented 5 years ago

Task for Quebec City meeting... Given #11 and that the use of an info-resource HTML view is primarily a developer of especially savvy / curious non-developer, what should the HTML view include visually and functionally? Tabbed/sorted representation list? Collection capabilities in related features list? Multi-language support options? etc.

alpha-beta-soup commented 5 years ago

Why not everything that is in the structured data? That seems to be Google's recommendation:

Structured data is coded using in-page markup on the page that the information applies to. The structured data on the page should describe the content of that page. You should not create blank or empty pages just to hold structured data; nor should you add structured data about information that is not visible to the user, even if the information is accurate.

(Emphasis mine.)

If I were writing an application that produced HTML with embedded structured data, I would probably write it in such a way that the HTML is generated from the structured data. This would be true whether it was rendered on the server or client. In the process of rendering HTML, I would inspect the data for some indication of type and then render web components according to what I expect that type to have (e.g. it understands that a film has at least one actor; an event has a venue). Unexpected types would necessarily have some kind of fallback.

Links to related things might be handled with a new page, or as lazy-loaded elements where the application fetches some more structured data, appends it to the page head and then renders something like a new web component within the existing DOM.

The layout/presentation/behaviour of that (tabs etc.) is just moot: as long as the page continuously presents the same thing to a human as to a machine reader, keeping the inconsistencies to an absolute minimum, then what does it matter? The superficial presentation can change at any time without affecting the actual content.

(Reading myself back, I now get the feeling that you're asking about demonstration presentation/functionality for the specific set of things identified in #11, rather than a more generic question about concordance between structured data and the HTML representation. Rather than deleting my comment, I'll leave it here in case it drives some related discussion, or if I have correctly interpreted you. Google's recommendations are good anyway. This is an interesting problem with client-side JavaScript and SEO; it makes me think of cloaking.)

alpha-beta-soup commented 5 years ago

My summary of the Québec discussion:

General acknowledgement that a HTML representation is primarily intended for human consumption, but will be parsed by search engine robots and indexed. Accessibility (i.e. screen readers) is enhanced by use of semantic HTML.

<head>
- Recommend the embedding of the JSON-LD representation as a <script> with type application/ld+json (data block) in the <head> of the HTML. (Within the <body> is acceptable as an alternative, but not preferred.) This can be generated by the server, and so present in the HTML representation without/before any client-side JavaScript is run. Consensus seemed to be that mandating complete server-side rendering of the <body> is not necessary, since Googlebot (and other robots) now execute JavaScript. However this isn't universal and there may be SEO benefits to server-side rendering.
- Mandate including <link rel="canonical" href="{NIR}" /> in the <head>
- The embedded JSON-LD shall always have a link to the node serving the page.
<body>
- Recommend appropriate use of semantic HTML elements, with only one specific recommendation: the human-readable content that matches the embedded JSON-LD document should be contained within a <main> element. This implies that the <main> can stand alone from incidental page content, such as institutional footers and navigational components, and helps to avoid being penalised by search engines (e.g. for cloaking or spamdexing, even if unintentional).
- Recommend links (<a>) to download the available non-HTML representations of the resource.

Language

Requirement: if multiple languages are available, language shall be supported through language negotiation. The URL path shall be language neutral.

Recommend: language can be handled through query parameter override (e.g. language=en).

Task: reference implementation of a selfie conformant HTML page

<link rel="bookmark">{NIR}</link> in the <head> was discussed but dismissed: counter-intuitively, this has nothing to do with a canonical/bookmarkable URI for browsers and is not recommended unless used for its actual purpose.

There is a potential issue with large list of links (see https://geoconnex.ca/gsip/info/swmonitoring/WSC_02OJ024). It’s possible to use JavaScript to make a pagination UI, but the JSON-LD document itself will have all of the links regardless. Example: https://demo.pygeoapi.io/master/collections/lakes/items/?startindex=0 No recommendation was made.

Some asides of my own:

I didn't think of it at the time, but I think it's probably a good idea to include the value schema:name in the <title> (as the entirety of the <title>, or just part of it, e.g. "River Monitor X | USGS" or "River Monitor X").
"Classless CSS resets" and user agent stylesheets do better with semantic HTML.
Custom Elements (Web Components) are an interesting emerging practice. It would be possible to write a generic Web Component for a particular type of entity, and pass the JSON data to a constructor to render one consistently. These can be shared easily and re-used by different organisations to visualise the same type of Thing. It could be possible to have a "gallery" of components to cover cases such as "infobox", "map", etc.
- https://developer.mozilla.org/en-US/docs/Web/Web_Components
- https://www.webcomponents.org/
Include links to the same page with supported languages (using parameter overrides)?

dblodgett-usgs commented 5 years ago

@jkreft-usgs @mbucknell @abhritchie -- are you happy with this summary to call this issue close or is there more to be done here?

abhritchie commented 5 years ago

Looked good to me (as very much not a web developer). I've added it to a md doc in my local version of the GitHub repo and will soon commit it as the starting point of a note on resource HTML representations. I'd be grateful if @alpha-beta-soup , @mbucknell and @jkreft-usgs (and others) could work on turning the document into prose as out testing progresses.

jkreft-usgs commented 5 years ago

I think that this is pretty solid. Thanks for the write-up @alpha-beta-soup

opengeospatial / SELFIE

What should an info-resource html page include? #16

Language