Write Guides

Write Guides

Overview

Use this skill for Remix guide chapters, especially docs/guides/app/actions/docs/chapters/*.md.

The goal is guide prose that sounds like a person walking through real Remix code: concrete, direct, slightly conversational, and careful with examples. Avoid polished filler, repeated takeaways, and abstract claims that could fit any framework.

Read First

Before editing a guide chapter:

1. Read docs/guides/app/actions/docs/chapters/01-start-here.md for voice and example style.
2. Read the target chapter completely.
3. Read adjacent chapters when the target chapter refers to earlier or later concepts.
4. If the chapter explains Remix app code, load the remix skill or relevant Remix references before inventing patterns.
5. If the task is only to identify AI-sounding prose, report findings with line numbers and do not edit unless asked.

Voice

Match 01-start-here.md:

• Start from what the reader just did or will do next.
• Use concrete files, URLs, routes, handlers, components, and responses.
• Use we for walkthrough steps and you for choices the reader controls.
• Keep paragraphs short. One idea per paragraph is usually enough.
• Explain code immediately after showing it, but do not narrate every line.
• Let examples carry the explanation when they can.
• Use small bullets for dense facts such as file roles, route expansions, and context fields.
• Link to other chapters when a topic deserves its own treatment, but do not use links as a substitute for the local explanation.

Chapter intros can set scope. A short paragraph before the first section that names what the chapter covers and where it sits in the request path is welcome, and it can be more thesis-like than a section opener. The line to hold is grounding: the intro should name the concrete files, APIs, or stages this chapter actually walks through, not make a generic claim that could open any framework guide. 01-start-here.md does this with its six principles and "What is Remix?" section. Section openers stay tighter and start from the concrete work.

Good guide phrasing:

Back in `routes.ts`, add the edit route with `form(...)`.

Since `albums.edit` is a nested route map, give it its own controller.

Open `/albums/thriller/edit`. The route now returns an HTML form with the album data filled in.

Avoid AI-Sounding Patterns

Cut or rewrite prose that has these tells:

• Abstract thesis sentences before the concrete work starts. This applies to section openers; a chapter intro can state scope as long as it names the concrete files, APIs, or stages the chapter covers.
• Generic claims like “doing real work,” “seamlessly,” “robust,” “powerful,” “unlock,” or “designed to make it easy.”
• “One source of truth” unless the paragraph immediately shows the exact typed value and what breaks when it changes.
• Repeating the same idea before and after an example.
• Staccato explanation where several short sentences define obvious neighboring parts in a row. Combine related clauses when it reads more naturally.
• Semicolons used as prose punctuation when a period, comma, colon, or split sentence would read more naturally. This does not apply to code snippets, which should follow the local Prettier config.
• Soft transitions such as “Additionally,” “Furthermore,” “It is important to note,” “A few things to keep in mind,” or “This is where X comes in.”
• Placeholder nouns such as “thing,” “stuff,” “pieces,” or “functionality” when a precise noun exists.
• Overconfident reassurance such as “TypeScript tells you every place” or “the failure is loud.” Say what actually happens.
• Generic web advice that could belong in any framework guide.
• A summary paragraph that restates the section instead of moving the reader forward.

Prefer:

Remix checks this during router setup. If a controller is missing an action for a leaf it owns, setup throws before the app starts serving requests.

Avoid:

This keeps ownership explicit and makes failures loud, ensuring your app stays in sync as it grows.

Structure

Value pedagogical reordering. A guide should introduce ideas in the order that helps the reader build the model, not necessarily in the order the API reference would list them. It is often better to show the explicit shape first, then introduce helpers as shorthand. For example, teach a full route object with { method, pattern } before get(...), post(...), or form(...) when that makes leaves, branches, and generated helpers easier to understand.

Keep guides distinct from API overviews. Teach just enough syntax or API surface for the reader to understand the guide, show the power of advanced usage with one strong example when it helps, then link to the API overview for the full grammar or exhaustive details. Avoid duplicating feature-by-feature reference docs inside a guide.

For guide chapters:

1. Keep the frontmatter title and description unless the chapter scope changes.
2. Preserve explicit heading anchors that are already linked from other chapters.
3. Introduce each section with the smallest amount of context needed.
4. Order concepts for learning: concrete shape first, shorthand second, edge cases last.
5. Prefer “look what I can do” examples over slow feature-by-feature tours when showing advanced capabilities.
6. Show code before long explanation when the code is the object being explained.
7. Put related explanation adjacent to the code or list it describes.
8. End sections by pointing to the next practical detail, not by restating the thesis.

For tutorials:

1. State the next thing the reader will build or change.
2. Show the file path and command or code.
3. Explain what changed and how to see it work.
4. Mention related chapters only after the reader has enough local context.

For concept chapters:

1. Start from the concrete app surface: files, imports, functions, route maps, responses.
2. Use one running example when possible.
3. Prefer the most explicit form before helpers, aliases, or generated shortcuts.
4. Teach the common case directly, then summarize advanced cases in a compact list or one expressive example.
5. Name the rule, then show the consequence in code.
6. Prefer a short table or bullets over parallel paragraphs when comparing related pieces.