|
 |
The Conference Web Page Looked Great, But The Slack Preview Didn't
A missing image and a mismatched copy sent me looking into the Open Graph protocol, and into a quality check single-source documentation publishing usually skips
|
| |||||||||||||||
I shared a hyperlink in a Slack channel recently. I was disappointed when I saw the way the page link preview displayed there. The web page I shared the link to pointed to a conference website that contained a promo image and details about the event. The Slack preview didn’t contain any image, and the accompanying text was about the organization hosting the event, not about the conference, as one might expect.
Chances are good you’ve seen this behavior before. And, if you’re like me, you might not know why.
Where Web Previews Come From
The visualization that platforms like Slack, Facebook, and BlueSky generate when you paste a hyperlink is supposed to contain the same info humans see when they visit the page the link points to. Looking into why that doesn’t always occur led me to a separate layer of metadata in a page’s <head>, and to a specification called the Open Graph protocol.
Introduced by Facebook in 2010, Open Graph provides a universal format for web publishers to control precisely how their URLs and website content are displayed when shared across social networks and messaging platforms. It gives web publishers a way to specify a title, description, image, and other info that platforms can use to determine what content will display in a link preview.
 |
What Was Broken
In the Slack example, the image was the first thing I noticed missing. No event photo appeared in the card, the way it did on the web page I visited. The copy didn’t discuss the conference. Instead, it showed a description of the event production company.
The headline was accurate. It displayed the conference name and dates, but the rest of the content was a mismatch.
One Possible Explanation
The site’s template may explain it. When page-level Open Graph values aren’t supplied, a web page preview may fall back to the site-wide default, producing generic copy about the organization that owns the site, instead of anything specific to the event they were promoting.
An Assumption That Needs Some Scrutiny
Increasingly, web-based documentation includes a share button to help users easily distribute our content to others. When someone clicks the share button they likely assume the shared link will display the content correctly wherever it lands.
But, that assumption doesn’t always hold true.
Tech writers typically check published output in the channels we control.
A PDF user manual gets reviewed as a PDF file.
Our help site gets checked for the experience users will have when they access that information using a web browser.
Shared link previews, on the other hand, are seldom discussed in tech comm circles and aren’t commonly included in pre-deployment review. That needs to change because they impact the customer experience. Link previews deserve scrutiny and to become part of our publication workflow quality control process.
The “Big Three” Tags For Writers
While there are dozens of Open Graph tags covering everything from video durations (video:duration) to property types (og:type), tech writers need to pay attention to three fundamental properties.
Here is what they look like in the markup, and how to approach writing them.
1. The Title (og:title)
This is HTML markup that controls the bold headline of your preview card.
<meta property="og:title" content="How to Generate an API OAuth Token" />
While it is tempting to just map this directly to your <title> or <h1> tag, your og:title should be optimized for standalone context. A page in your doc portal site might be titled “OAuth Tokens” because it lives under an “Authentication” breadcrumb. But stripped of that breadcrumb in a Slack channel, “OAuth Tokens” is vague. Your og:title should be descriptive and independent.
2. The Description (og:description)
This is the one-to-two sentence summary that appears below the title.
<meta property=”og:description” content=”Learn how to generate, secure, and refresh 0Auth tokens for the v2 REST API.” />
Unlike a traditional SEO meta description (which is written to for search engine algorithms), an og:description is a direct pitch to a human being in a chat window. Keep it punchy and action-oriented. Aim for under 100 characters