Skip to content

Explain instruction scope and combining rules in the custom instructions guide - #416

Open
shirgoldbird wants to merge 1 commit into
mainfrom
custom-instructions-scope
Open

Explain instruction scope and combining rules in the custom instructions guide#416
shirgoldbird wants to merge 1 commit into
mainfrom
custom-instructions-scope

Conversation

@shirgoldbird

@shirgoldbird shirgoldbird commented Jul 28, 2026

Copy link
Copy Markdown
Member

Summary

Support has seen recurring confusion from customers on custom instructions.

The custom instructions guide covered how to phrase instructions but not what they're suited for or how multiple instructions interact. This PR adds:

  • "How instructions are applied": instructions apply while the text is translated, passage by passage, not as an editing pass over the finished document, so whole-text structural instructions restructure every passage instead of the document once. Includes the rule of thumb (target the structure of one or more sentences, never the entire text) and a good/bad structural example pair, plus the workaround (translate with local instructions, restructure separately).
  • "Combining multiple instructions": no priority order exists; broad transformative instructions dominate more specific ones; add and test instructions one at a time.
  • A pointer from the style rules guide, since custom instructions are commonly written inside style rule lists.

No internal implementation details (chunk sizes, model training behavior) are exposed.

Test plan

  • mint broken-links --check-anchors: no issues in the two edited pages (two pre-existing findings elsewhere are untouched)

🤖 Generated with Claude Code

…ons guide

Customers writing whole-text structural instructions (reorder the
argument, convert lists to prose) see translation quality drop and
don't understand why. Document that instructions are applied per
passage rather than as an editing pass over the finished document,
that sentence-level scope is the intended use, and how multiple
instructions interact, with good/bad structural examples.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@mintlify

mintlify Bot commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
deepl-c950b784 🟢 Ready View Preview Jul 28, 2026, 8:14 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@mintlify

mintlify Bot commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
deepl-c950b784 🟡 Building Jul 28, 2026, 8:13 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant