菜单
Use when: drafting or reviewing documentation content; enforcing Qlik style, clarity, structure, accessibility, and localization standards; ensuring consistency across all Qlik documentation regardless of format.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Analyze GitHub pull requests to understand product changes for documentation planning. Use when: you have PR URLs from Jira or direct input, need to understand code/UI changes, want to identify affected features, or must draft docs based on a merged or open PR. Reads PR metadata, diffs, and source files to extract documentation-relevant details.
Fetch Jira issue context for documentation work. USE FOR: reading a Jira ticket, extracting fields, reading linked Jira issues for background, scanning description/comments for inline URLs, and summarizing the product change.
基于 SOC 职业分类
| name | qlik-writing-guidelines |
| description | Use when: drafting or reviewing documentation content; enforcing Qlik style, clarity, structure, accessibility, and localization standards; ensuring consistency across all Qlik documentation regardless of format. |
Format-agnostic writing guidelines for all Qlik documentation. Markup-specific validation is handled by separate skills (flare-markup-validation, dita-markup-validation).
When resolving conflicts or gaps, apply in this order:
Prefer consistency with existing repository patterns. Flag conflicts with established patterns and suggest either updating the repository or making an exception.
Write titles and headings for user goals, not tool features.
Do not repeat the task title in the first sentence.
Do not describe self-explanatory UI elements.
Anticipate common errors and provide troubleshooting inline. Place warnings before the step where errors could occur.
For complex multi-step processes, create a main task linked to sub-tasks. Main task should be self-contained for advanced users; link to detailed procedures for others.
Introduce concepts only when needed for the current task. Don't front-load unnecessary conceptual information.
Start with basic, short procedures. Progress to complex tasks after establishing foundation.
Put most important content first in titles, headings, and opening sentences. Use inverted pyramid style. Place actionable text before explanatory.
Keep headings short and keyword-rich (max 7 words). First sentence after heading should stand alone.
Use bulleted lists for scannability. Keep paragraphs short and focused. State main point first. One idea per paragraph.
Use sparingly; consider if information belongs in prerequisites or steps instead. Avoid images in notes. Avoid long notes.
Use descriptive link text (never "click here" or raw URLs). Do not use "the" before a link to a guide.
Break sentences >25 words. Avoid modifier stacks (max 3 words per noun phrase). Target grade 8 readability.
Use "click" (not "click on") for commands, command buttons, option buttons, and list items. Avoid "choose", "select", "pick" for menu commands.
Use "select" for check boxes, drop-down items, and file paths. Use "clear" for unchecking boxes. Use "remove the checkmark" for toggle commands.
For combo boxes, use "type" or "select". Use "enter" if no confusion is possible.
Use "points to" when describing submenu opening. User points to main menu command (submenu opens), then clicks the desired command.
Use sentence-style for headings and UI elements. Follow the UI exactly for labels and buttons. Do not capitalize generic identifiers.
Refer to unavailable commands as "unavailable", not "dimmed", "disabled", or "grayed". Exception: Use "dimmed" or "grayed" when describing appearance.
Use active voice; minimize passive unless actor is irrelevant.
Avoid starting sentences with And, So, But.
Replace vague verbs with precise ones: configure, select, deploy, generate, create, delete, update, enable, disable.
Remove redundant lead-in phrases.
Use optional pronouns and articles to clarify structure for global audience.
Give conclusion first. Put key information at start. Users should know whether to keep reading within first sentence.
Heading levels should not skip. Headings must be descriptive and keyword-rich.
Link text must be descriptive and make sense out of context. No "click here", "read more", "this link".
Supply alt text describing function/purpose (not appearance). Use punctuation unless inline icon. For UI images, describe what user should see or do, not pixel details.
Avoid conveying meaning by color only. Add textual cues (e.g., "Required fields are marked with an asterisk (*) and appear in red.").
Ensure table headers use proper markup with scope. Provide caption or surrounding text explaining purpose.
Structure pages clearly with headings and accessible tables. Both humans and chatbots handle long pages if well-structured.
Use in-context links with short explanations before or after. Helps chatbots understand purpose.
Group related links under clear headings. Prevents clutter and improves readability.
Use clear, descriptive headings. Standardize terminology. Include keywords for user queries and AI searchability.
Ensure accuracy. Both humans and chatbots detect inaccuracies, destroying trust when users are already frustrated.
Do not create FAQ-style content solely for chatbots. Well-structured non-FAQ content works for all. Avoid FAQ sections in product documentation.
Glossary content serves both humans and chatbots. Definitions can start with or without the term. OK to define collocations as ", ".
Expand ambiguous time references. Spell out month names; use 24-hour time.
Avoid idioms and slang. Avoid contractions in UI labels. Use language understood by English speakers worldwide.
Avoid singular "they"; restructure for plural.
Avoid Latin and non-English words. Use English equivalents:
Limit nesting to one layer of clauses. Max 25 words per sentence. Avoid double negatives and fragments. Use lists and tables instead of complex structures.
Use optional articles and punctuation to clarify structure for localization.
Avoid modifier stacks. If noun phrases exceed 3 words, rewrite.
Prefer active voice and indicative mood. Use imperative in procedures.
Do not use titles unless necessary.
Do not use bullet lists for a single prerequisite; use plain text.
Avoid FAQ sections and content created solely for chatbots. Write for humans first; well-structured content serves all audiences.
First occurrence: Qlik®. Subsequent: Qlik.
Use Qlik as adjective, not possessive.
Preserve official product/component names exactly. Do not coin abbreviations. Consult terminology committee for new terms. Use same terms across product, documentation, and marketing.
Before considering content complete, verify:
