l-guide-writing-wisdom

Reference guide article writing best practices when creating product guide series. Use when: (1) Starting a new guide article series, (2) Writing individual guide episodes, (3) Planning image captures...

Guide Article Writing Reference

Look up guide article writing best practices from the documentation.

How to Use

1. Read the full guide article writing doc at doc/src/content/docs/writing/guide-article-writing.md
2. Also read the writing style doc at doc/src/content/docs/writing/writing-style.md for tone rules
3. Also read the markdown writing rule doc at doc/src/content/docs/writing/markdown-writing-rule.md for MDX/markdown formatting rules (headings, lists, emphasis)
4. Apply the relevant patterns based on the user’s current task
5. Mention the source doc paths so the user can find them for further reading

Essential Quick Reference

Placement First (series & base branch)

Before drafting, decide which series the article joins and which base branch it sits on. Precedence (stop at first match):

1. Existing series for this product → add as next -ep{N+1}, continue the active sub-base or base/wip-articles directly
2. User-specified series (--series=<slug>) → add to that series
3. Tiny one-off article with no series → standalone {product}-guide.mdx directly on base/wip-articles, no themed sub-base
4. Multi-article epic / porting (~5+ articles, modernization) → new base/wip-articles-<theme> sub-base

Full rule: “Placement Decision” in doc/src/content/docs/writing/guide-article-writing.md, mirrored in the repo-root CLAUDE.md “Placement rules” section.

Workflow Order

1. Watch YouTube source video, get transcript via /youtube-text-fetch
2. Plan article structure from transcript
3. Capture key video frames as images
4. Build custom explanation component if needed (develop in Storybook)
5. Write JA article with balanced image/text mix
6. Process images: imgs/ → pnpm convimgs:upload → pnpm build:metadata
7. Prepare OGP/thumbnail images (__og suffix)
8. Review and polish JA version
9. Create EN translation as final phase via /l-create-en-implementation

Image/Text Balance Rule

• Never have more than 2-3 paragraphs of text without a visual break
• Every parameter or feature explanation should have an accompanying image or diagram

WIP Image Components (during writing)

During article development, use these WIP components instead of <ArticleImage>:

All three components show debug info and are blocked from main by the CI guard (check:capture-wip).

WIP <YoutubeAt> and the Pick Cover dialog: In pnpm dev, each WIP <YoutubeAt> shows a Pick Cover button. The cover auto-derives from ?t=N to the nearest 2-second capture. Clicking “Pick Cover” opens a gallery dialog so the human author can select a better frame. The dialog writes the picked capture filename back into the MDX file via the capture attribute. Always run the Pick Cover pass before finalizing.

When finalizing: Run /l-youtube-guide-writer --finalize <mdx-path> (Step 10 in the skill). This handles slug derivation, R2 upload, and MDX rewriting for all WIP components.

All WIP images live in the image-stash directory (symlinked to $HOME/repos/zp/zmod-image-stash, a separate git repo).

Production Image Components (finalized articles)

• Use <ArticleImage slug="..." caption="..." /> for finalized images served from R2 CDN
• Use custom components (e.g., <OxiGridFigure>) for interactive UI simulations

Custom Component Checklist

• Design props for declarative MDX usage
• Must be responsive (mobile + desktop)
• Use <figure> + <figcaption> pattern
• Develop and verify in Storybook
• Consider reuse across multiple episodes

Image Naming

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

Article Voice: Video Writedown Style

Guide articles use the video writedown voice — balanced prose derived from video content. Read the full spec at doc/src/content/docs/writing/guide-article-writing.md (section “Article Voice: Video Writedown Style”).

Core principle: AI writes facts, technical explanations, and operation descriptions. Emotional commentary is added by the human author later.

Write: Technical facts, operation steps with bold button names, contextual explanations (why/when), brief section summaries, practical tips

Don’t write: Personal feelings (感動した), importance markers (ポイントは, 面白いのは), conversational fillers (〜ですよね), dramatic emphasis (革命的), tutorial commands (やってみましょう)

Tone: Polite です/ます base, mix of medium and short sentences, specific values and names, enough detail to understand but not exhaustive

Outro Rules

• Open-ended series: Never declare the series finished in an outro. Full rule: doc/src/content/docs/writing/guide-article-writing.md#open-ended-series

Writing Tone Rules

• Refer to doc/src/content/docs/writing/writing-style.md for full rules
• Do NOT write emotions/feelings unless the user explicitly provides them
• Do NOT use 〜ですよね endings
• Do NOT use ポイントは or 面白いのは without user direction
• Use specific parameter values, not vague descriptions
• Bold **button/knob names** in operation instructions

Markdown Formatting Rules (anti-AI-slop)

Full rules: doc/src/content/docs/writing/markdown-writing-rule.md. Key traps AI keeps falling into:

• Never use a **bold paragraph** as a section heading. Always use real ## / ### / #### headings. The to-avoid pattern is a paragraph whose entire text is wrapped in **...** (often followed by a colon), used to title the block beneath it. This breaks document outline, TOC generation, and screen-reader navigation. If a chunk of text deserves visual prominence as a section title, it deserves a real heading.
• Bold (**) and italic (*) are for inline emphasis only — single words or short phrases inside a sentence.
• For a list of name: description items (e.g. modules in a rack, parameters), do not auto-bold every name. Plain - Name: description is the default; reserve bold for cases where the name is being emphasized inline against surrounding prose.

Translation (JA → EN)

• JA version must be complete and stable before starting EN
• Translate caption props but keep slug values unchanged
• Use standard English synth terminology
• Keep product names and mode names in original form

Pre-Publish Checklist

• All images uploaded to R2
• pnpm build:metadata executed
• OGP image set (imgThumb with __og slug)
• Correct tags and categories in frontmatter
• Components render correctly on mobile and desktop
• EN captions translated
• Storybook stories for custom components