UX IQ Article Guidelines

This playbook describes the structure and content conventions each post should follow so the layout renders correctly and the experience stays consistent across the site.

1. Front Matter Template

Every article must begin with the following YAML block (update the values as needed):

---
layout: post
title: "Your Title"
author: Your Name
dek: One-sentence value proposition for the piece.
description: 150–160 character meta description for SEO.
summary: 1–2 sentences that describe the key takeaway. Shown above the byline.
categories: [primary-category]
tags: [primary-tag, secondary-tag]
image: https://...
image_alt: Short accessible description of header image.
image_credit: Photo credit with source.
---

Field Notes

• dek: concise teaser that appears under the title; keep to ~140 characters.
• description: used for meta tags (SEO, Open Graph, Twitter). Aim for 150–160 characters, no markdown.
• summary: surfaced both in the header callout and the RSS feed. Avoid markdown here.
• categories / tags: use existing taxonomy where possible so related-article matching finds strong matches.
• image: full-width hero image (16:9 recommended). Always provide image_alt and image_credit.

2. Opening Section

Start the markdown body with an intro paragraph that frames the problem and hooks the reader.

Immediately follow the intro with the “In This Article” table of contents block:

<nav class="post-toc" aria-label="In this article">
  <h3 class="post-toc__title">In This Article</h3>
  <ul class="post-toc__list">
    <li><a href="#heading-slug-1">Heading Title 1</a></li>
    <li><a href="#heading-slug-2">Heading Title 2</a></li>
    <!-- Add one list item per major section -->
  </ul>
</nav>

• Ensure every major section uses an ### heading so anchors (#heading-slug) match.
• Keep heading text sentence case for readability.

3. Body Structure

1. Section headings (###): outline the core steps or ideas.
2. Paragraphs: prefer short paragraphs that state the insight first, then supporting detail.
3. Lists: use unordered or ordered lists for step-by-step guidance. Avoid nesting beyond one level.
4. Callouts / quotes: use > blockquotes to highlight key statements.

4. Images & Media

• Inline images should be centered, 16:9 or 4:3, and use descriptive alt text.
• Host assets on a reliable CDN (Unsplash, own Cloudinary bucket, etc.).
• Include attribution immediately after the image if required.

5. Related Articles Behavior

The layout automatically surfaces up to four related posts using this priority order:

1. Same primary tag (tags[0]).
2. Same primary category (categories[0]).
3. Most recent remaining posts, excluding the current article.

To improve relevance:

• Choose descriptive tags shared by other posts.
• Keep categories limited to the curated set (e.g., research, strategy, operations).

6. Writing Voice & Style

• Tone: practical, friendly, informed. Write as if guiding a cross-functional product team.
• Perspective: use first person plural (“we”, “our teams”) when describing processes.
• Clarity: lead sections with the recommendation, follow with rationale, then actionable detail.
• Length: target 900–1,400 words.

7. Pre-Publish Checklist

• Front matter fields validated (title, dek, summary, image, tags/categories).
• Intro paragraph hooks the reader and contextualizes the problem.
• Table of contents updated with all major sections.
• Headings follow a logical hierarchy (###, no skipped levels).
• All images include alt text and credits.
• Links tested (internal + external).
• Markdown renders without Liquid errors (bundle exec jekyll build).

Following this guideline ensures every UX IQ article plugs neatly into the shared layout, drives accurate related-article recommendations, and maintains a consistent storytelling style.