Prompting
Master the art of prompting to get the best results from Ask AI. This guide covers how prompts work in DocSearch v4, shares proven techniques from leading AI providers, and provides practical examples to help you create effective, on-brand AI responses for your documentation.
What you'll learn:
- How Ask AI uses prompts alongside your content
- Proven prompting techniques and patterns
- Common pitfalls and how to avoid them
- Security and compliance best practices
1. How prompting works in Ask AI​
- Base system prompt (hidden) - Every Ask AI request starts with a proprietary system prompt that enforces safety, retrieval and tone.
- Your complementary system prompt - A short set of extra instructions you provide (e.g., "Answer like a Kubernetes SRE. Prefer concise bullet points.").
- The user question - What your visitor types in the chat box.
- Context passages - Relevant chunks from your Algolia index, automatically inserted.
Only step 2 is in your hands; the rest is handled by Ask AI. Think of your prompt as a policy overlay rather than a full rewrite.
2. Principles of effective prompts​
| Goal | What to do | Why it helps |
|---|---|---|
| Be explicit | State role, style and constraints in the first sentence. | LLMs obey the earliest, clearest instruction. |
| Ground in context | Add product names, audience level, or domain jargon. | Reduces hallucinations and keeps answers on-brand. |
| Set format | "Answer in Markdown with H2 headings and a summary table." (we handled this for you) | Ensures consistent rendering in your site theme. |
| Show, don't tell | Give one or two short exemplars of the desired output. | Few-shot examples outperform general adjectives. |
| Limit scope | "If you're unsure, say I don't know." | Encourages honesty over speculation. |
| Iterate & test | Look at the feedback, tweak, re-run. | Prompting is an empirical craft - small wording changes matter. |
Tip - keep it brief Excessively long prompts push relevant document chunks out of the context window and slow responses.
3. Prompt patterns that work​
Style transfer​
You are a senior React maintainer. Explain concepts in the style of React docs: concise intro ➜ "Example" ➜ "Gotchas".
Persona + audience​
Act as a cloud-native Solutions Architect.
Audience: junior DevOps engineers migrating to Kubernetes.
Goal: explain trade-offs in plain English, no jargon.
Multi-step reasoning​
FIRST think step-by-step about possible causes.
THEN output only the final answer in bullet points.
4. Common pitfalls​
| Anti-pattern | What happens | Fix |
|---|---|---|
| Vagueness - "Explain this." | Generic or rambling answers. | Specify role, topic, length. |
| Prompt stuffing - 1 000-word instructions. | Context window overflow; higher cost. | Trim to the essentials. |
| Conflicting rules | Model picks one at random. | Merge rules or order them by priority. |
5. Security & compliance​
- Never paste secrets, PII or internal URLs into your prompt.
- Do not use company policies or other sensitive information in your prompt.
- Review a few generated answers for policy compliance while testing.
6. Learn more​
- OpenAI - Best practices for prompt engineering (help.openai.com)
- OpenAI Cookbook - GPT-4.1 Prompting Guide (cookbook.openai.com)
- Anthropic - Prompt engineering overview for Claude (docs.anthropic.com)
These resources include concrete templates, example libraries and advanced techniques like chain-of-thought prompting.
Quick checklist​
- Role and audience defined
- Desired format specified
- Examples included (≤ 2)
- Scope limits & fallback language added
- Tested against real user questions
Happy prompting — and remember: iterate, observe, refine!