Guide Article Writing

Workflow and best practices for writing product guide article series. Covers the full process from YouTube source material to published JA/EN articles.

This document covers the workflow and best practices for creating product guide article series. It is based on lessons learned from producing the OXI ONE MKII guide series (EP.1–EP.6).

Overview

A guide article series is a set of articles that explain a specific product across multiple episodes. Each article is built from official YouTube video material, combining video captures, text explanations, and custom components.

Key Principles

YouTube videos as the base: Official video captures and transcripts are the primary source material
Image and text balance: Text-only sections are hard to read. Insert images or components at regular intervals
Custom explanation components: Components that simulate product-specific UI are highly effective
JA first, EN last: Complete the Japanese version first; English translation is the final phase

Article Source: YouTube Videos

Transcript as Resource

YouTube video transcripts (subtitle text) serve as an excellent base for articles.

Use the /youtube-text-fetch skill to retrieve the video transcript
Use the transcript as a structural outline for the article
Follow the video’s explanation order when organizing the article

Do not use transcripts verbatim. Restructure spoken language into readable prose — directly transcribed speech reads poorly as written text.

Video Captures

Capture images from videos are essential visual elements in guide articles.

Capture screenshots of key scenes from the video
Focus on operation screens, parameter displays, and result screens
Place original HEIC/PNG files in the imgs/ directory and process them through the image pipeline

Article Structure

Frontmatter

---
title: "Product Name Guide EP.N: Episode Title"
description: >-
  EP.N of the Product Name guide series. What this episode covers.
imgThumb: product-promo-image__og
avoidListing: false
tags:
  - guide
  - product-tag
categories:
  - product-guide-series
  - guide
contentType: guides
createdAt: YYYY-MM-DD
updatedAt: null
---

Standard Sections

Introduction: Overview and context for the episode
YouTube embed: <Youtube url="..." />
TOC: ## TOC (auto-generated table of contents)
Body: Feature explanations organized by section
Practical Tips: Concrete usage advice
Outro: Next episode preview and product links

Image and Text Balance

Long text-only sections are hard to read. Follow these guidelines:

Insert an image or component every 2–3 paragraphs
Accompany parameter explanations with actual screen captures
Include before/after screenshots for operation instructions
Visualize abstract concepts with custom components

<ArticleImage slug="product-cap-feature-name" caption="Caption text" />

Too much text causes readers to disengage. Place images and components strategically to create visual rhythm.

Custom Explanation Components

Why Custom Components Matter

Custom components that simulate product-specific UI dramatically improve guide articles.

For the OXI ONE MKII guide series, the OxiGridFigure component was created to visualize sequencer grid states within the article. This enabled:

Explicit representation of patterns that are hard to understand from capture images alone
Intuitive before/after comparisons
Significant improvement in article visual quality

Component Design Guidelines

Pass data via props: Enable declarative data description within MDX
Responsive design: Display properly on both mobile and desktop
Figure + Caption pattern: Wrap in <figure> + <figcaption> with a caption
Develop in Storybook: Build and verify components visually in Storybook
Design for reuse: Make components generic enough to use across multiple episodes in the series

<OxiGridFigure
  steps={8}
  sideLabel="Before"
  connected
  pads={[
    { col: 0, row: 0, color: 'rgb(0, 200, 80)' },
    { col: 1, row: 3, color: 'rgb(0, 200, 80)' },
  ]}
  caption="Caption text" />

When to Create Custom Components

When the same type of information appears in multiple places
When UI states are difficult to convey with text alone
When before/after or comparison views are needed
When you want to simulate a product’s operation screen

Components can be prepared at any time, but it is best to assess the need during early episodes and start development early.

Image Pipeline

Workflow

Capture screenshots from the video
Place original images in the imgs/ directory (naming: product-cap-epN-feature-name.heic)
Run pnpm convimgs:upload to process and upload to R2
Run pnpm build:metadata to update the metadata DB
Use in MDX as <ArticleImage slug="product-cap-epN-feature-name" />

Naming Convention

Slug naming convention for capture images:

{product-prefix}-cap-ep{N}-{feature-name}

Examples: oxi-cap-ep1-mono-mode, oxi-cap-ep3-poly-mode-grid

Thumbnail and OGP

Prepare a shared thumbnail image for the series (with __og suffix)
OGP images are critical for social sharing — they appear when links are shared
Decide whether to use per-episode OGP images or a shared series image
Per-episode OGP reflecting each episode’s content is ideal, but a shared image is acceptable

OGP image preparation tends to get postponed, but always verify before publishing. Setting imgThumb to a slug with the __og suffix generates both WebP and OGP variants.

Translation Workflow (JA → EN)

Process

Complete the JA version first: Finalize all content, images, and components
Create the EN version in the final phase: Start translation only after the JA version is stable
Use /l-create-en-implementation: Automatically creates an EN branch based on the JA PR
Leverage the translation agent: The en-translator subagent preserves MDX structure during translation

EN Article Guidelines

Translate MDX component caption props to English
Keep slug and image slug values unchanged (JA/EN share the same images)
Use standard English synthesizer terminology (e.g., step, note, gate, velocity)
Keep product names and mode names as-is (e.g., Mono Mode, Poly Mode)

Article Voice: Video Writedown Style

Guide articles are video writedown articles — structured prose derived from YouTube video content. The preferred voice is a balanced middle ground: not a dry manual, not an emotional blog post.

The Goal

Transform video transcript + visual information into readable web articles. The AI writes facts, technical explanations, and operation descriptions. Emotional commentary and personal opinions are added by the human author later.

Voice Spectrum (where we sit)

Too dry (manual/memo)  ◄──────  ★ HERE  ──────►  Too emotional (blog/essay)
Var.A style                     First version       Var.B/D style

What to Write

Technical facts: What the feature does, how it works, what parameters are involved
Operation descriptions: Step-by-step how to use a feature, with bold button/knob names
Contextual explanations: Why a feature exists, when you’d use it, how it relates to other features
Structural summaries: Brief intro text per section that frames what follows
Practical tips: Concrete usage patterns and workflows

What NOT to Write

Personal feelings: 「自分が初めて使った時は感動した」— the AI didn’t use it
Importance markers: 「ここがポイントです」「面白いのは」— let the reader decide what’s important
Conversational fillers: 「〜ですよね」「〜なんですよね」— too casual for article format
Dramatic emphasis: 「驚くほど便利」「革命的な機能」— overstated
Tutorial commands: 「やってみましょう」「確認してみてください」— this is an article, not a workshop

Tone Guidelines

Aspect	Do	Don’t
Technical detail	Specific values and names	Vague descriptions
Sentence length	Mix of medium and short	All long or all choppy
Explanation depth	Enough to understand the concept	Exhaustive every-edge-case coverage
Summary text	Brief framing (1-2 sentences per section)	No summary, or multi-paragraph intros
Formality	Polite but not stiff (です/ます base)	Too casual (だよね) or too formal (である)

Example: Good Balance

## パターン長の設定

OXI ONE MKIIのシーケンスは最大128ステップで構成されますが、
すべてのステップを使う必要はありません。**Init**と**End**で
シーケンスの開始位置と終了位置を指定することで、
必要な長さのパターンを作成できます。

<YouTubeCaptureWip ... />

**Init**を押しながらステップボタンを押すと開始位置、
**End**を押しながらステップボタンを押すと終了位置が設定されます。
ピンク色のバーがパターンの長さを視覚的に表示します。

This is the right level: explains what the feature does, how to use it, and what visual feedback to expect — without telling the reader how they should feel about it.

Anti-Patterns by Variation

Style	Problem	When it IS appropriate
Memo/reference (Var.A)	Too dry for web reading — feels like a spec sheet	Printed quick-reference card
Emotional narrative (Var.B)	AI invents feelings; reads as someone else’s diary	When the human author writes personal sections
Step-by-step tutorial (Var.C)	「やってみよう」format assumes workshop context	Actual hands-on workshop materials
Casual conversation (Var.D)	Too rough for a shop’s public content	Podcast show notes or friend-to-friend sharing

Writing Tone for Guide Articles

Guide article tone follows the rules in Writing Style, with these additional considerations:

Explanatory tone: Not textbook-like, but as if someone who has actually used the product is explaining it
Reference specific parameter values: “Set Density high” → “Set Density to 80%–100%”
Clear operation instructions: Emphasize button and knob names with **bold**
Practical advice in Tips sections: Show concrete usage patterns, not just theory

Series Management

Guide Series Data

Guide series information is managed in src/data/guide-series/. Articles belonging to a series include the series category key in their frontmatter categories.

Episode Numbering

Number episodes as EP.1, EP.2, …
File naming: {product}-guide-ep{N}.mdx (e.g., oxi-one-mkii-guide-ep1.mdx)
EN version: {product}-guide-ep{N}.en.mdx

Cross-Episode Consistency

Use the same terminology across all episodes
Maintain consistent custom component usage
Standardize introduction and Outro formatting
Link between episodes when cross-references exist

Open-ended Series {#open-ended-series}

Guide series are open-ended — new episodes may be added at any time. Outros must not declare the series finished.

Forbidden framings:

JP: 最終回 / シリーズはここまで / シリーズは完結 / 完結編 / 最後のエピソード / ラストエピソード / 最終話 / このシリーズはこれ / 最後の記事
EN: this series ends / series ends here / final episode / final installment / this is the last / concludes the series / wraps up the series / the last article / end of the series

Preferred outro style: Recap the current episode’s takeaways or hint at future episodes. Retrospective summaries (“EP.1 covered X, EP.2 covered Y”) are fine — only termination framing is forbidden.

WIP Article Base Branch Flow

Guide articles are drafted and accumulated in a long-lived WIP branch before being individually published. This lets AI write drafts quickly while humans finalize at their own pace.

For the full workflow detail, see the “WIP Article Base Branch” section in CLAUDE.md (the repo root CLAUDE.md is the source of truth). This section provides a concise overview of how it fits into guide article writing.

How It Works

New drafts are ported into base/wip-articles (a long-lived branch, never merged wholesale into main)
Theme-scoped epics use base/wip-articles-<theme> branches (e.g., base/wip-articles-oxi-coral)
Finalization uses the /l-youtube-guide-writer --finalize <mdx-path> skill
Each finalized episode gets its own small PR targeting main — the base branch itself is never merged directly

Placement Decision (Series & Base Branch)

Before drafting, decide which series the article belongs to and which base branch it sits on. Apply this precedence from top to bottom and stop at the first match:

Existing series continuation — if a guide series already exists for the target product (search both main and any base/wip-articles* branch), add the new article as the next -ep{N+1} of that series. Update src/data/guide-series.mjs if needed. Do not start a parallel series for the same product.
User-specified series — if the user explicitly names a target series (e.g., via --series=<slug> in the skill invocation), use that series even if rule 1 would pick a different one.
Tiny-module single article — for a one-off short video of a small module with no existing series (e.g., a 2-minute brand overview of a utility), draft a standalone article ({product}-guide.mdx, no episode number) and park it directly on base/wip-articles. Do not create a themed sub-base for a single tiny article.
Multi-article epic / porting — for bulk work (~5+ episodes, modernizing stale drafts, porting from an old branch), open a themed sub-base base/wip-articles-<theme> and run it as an epic.

The guiding principle: series and base branch are orthogonal axes, and both default to “reuse what exists”. Only introduce a new series or a new sub-base when the scope clearly justifies one.

When in doubt between standalone ({product}-guide.mdx) and EP.1 ({product}-guide-ep1.mdx) for a tiny module: ask the user. If more videos for the same product are likely to appear later, go EP.1 and register the series up-front so future episodes slot in cleanly.

Example Flow

# 1. Draft is written and parked in base/wip-articles (or base/wip-articles-<theme>)
#    Article sits here with <YouTubeCaptureWip> placeholders, WIP frontmatter, etc.

# 2. When ready to publish a single episode:
/l-youtube-guide-writer --finalize src/mdx/guides/oxi-coral-guide-ep1.mdx

# 3. The skill handles image finalization, component replacement, metadata update
#    Then creates a small PR targeting main with just this finalized episode.

# 4. PR is reviewed and merged. main gets exactly one finalized episode.
#    The base WIP branch continues accumulating future drafts.

Canonical Reference: OXI Coral Series

The OXI Coral series EP.1–5 on main is the canonical example of the finalized article shape. When in doubt about what a finished guide article should look like — structure, image usage, component patterns, voice — refer to those articles.

Article Finalization: WIP to Production

When an article is ready to release, convert WIP components to production ArticleImage components.

Step-by-step

Copy captures to imgs/ with proper slug names:
```
cp image-stash/{videoDir}/captures/capture-HH-MM-SS.jpg imgs/oxi-cap-ep7-feature-name.jpg
```
Naming convention: {product-prefix}-cap-ep{N}-{feature-name}.jpg
Process and upload: pnpm convimgs:upload (generates WebP variants + uploads to R2)
Update metadata: pnpm build:metadata (adds new slugs to metadata-db.json)

Replace components in MDX: Change all <YouTubeCaptureWip> to <ArticleImage>:

<!-- Before (WIP) -->
<YouTubeCaptureWip
  videoDir="20260326-VIDEO_ID-slug"
  capture="capture-00-01-42.jpg"
  id="ep7-feature"
  caption="Caption text" />

<!-- After (production) -->
<ArticleImage slug="oxi-cap-ep7-feature" caption="Caption text" />

Remove temp captures: Delete the article’s oxi-cap-ep7-* files from static/images/temp-article-caps/
Update frontmatter category: Change wip to the proper series slug (e.g., oxi-one-mkii-guide)
Commit metadata-db.json: The updated metadata DB must be committed

Important notes

Do NOT delete captures from image-stash/ — it is a shared archive. Other articles or future sessions may reference the same video captures
Do NOT delete imgs/ source files — they are the originals for R2 processing
The check:capture-wip CI guard blocks any PR with remaining <YouTubeCaptureWip> or <WipImg> components from merging to main