| 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. |
Qlik Writing Guidelines Skill
Format-agnostic writing guidelines for all Qlik documentation. Markup-specific validation is handled by separate skills (flare-markup-validation, dita-markup-validation).
Source Authority Hierarchy
When resolving conflicts or gaps, apply in this order:
- Writer's explicit instructions and provided source files/snippets
- This skill content (Qlik-specific guidelines for all formats)
- Microsoft Style Guide (adapted to Qlik rules; reference: https://learn.microsoft.com/en-us/style-guide/welcome/)
- General technical writing best practices
Prefer consistency with existing repository patterns. Flag conflicts with established patterns and suggest either updating the repository or making an exception.
Task-Oriented Documentation Principles
Focus on User Goals
Write titles and headings for user goals, not tool features.
- โ
Good: "Configure email alerts"
- โ Bad: "Email alerts configuration dialog"
Eliminate Redundancy
Do not repeat the task title in the first sentence.
- โ Bad: "To edit your information, do the following:"
- โ
Good: "You can update your email, password, and profile picture."
Avoid the Obvious
Do not describe self-explanatory UI elements.
- โ Bad: "In the Name field, enter the name."
- โ
Good: "Enter a descriptive name for the connection."
Support Error Recovery
Anticipate common errors and provide troubleshooting inline. Place warnings before the step where errors could occur.
Structure Complex Tasks
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.
Give Information "Just in Time"
Introduce concepts only when needed for the current task. Don't front-load unnecessary conceptual information.
Build Confidence
Start with basic, short procedures. Progress to complex tasks after establishing foundation.
Content Organization and Scannability
Hierarchical Structure
Put most important content first in titles, headings, and opening sentences. Use inverted pyramid style. Place actionable text before explanatory.
Headings
Keep headings short and keyword-rich (max 7 words). First sentence after heading should stand alone.
Lists and Paragraphs
Use bulleted lists for scannability. Keep paragraphs short and focused. State main point first. One idea per paragraph.
Notes and Tips
Use sparingly; consider if information belongs in prerequisites or steps instead. Avoid images in notes. Avoid long notes.
Cross-References
Use descriptive link text (never "click here" or raw URLs). Do not use "the" before a link to a guide.
- โ
Good: "see [Activating your account]"
- โ Bad: "see the [Activating your account]"
Length and Structure Limits
Recommended Maximums
- 6 sentences per paragraph
- 20 words per task step
- 7-9 steps per task (break into sub-tasks if more)
- 25 words per concept sentence
Sentence Structure
Break sentences >25 words. Avoid modifier stacks (max 3 words per noun phrase). Target grade 8 readability.
Verbs for UI Interaction
Click
Use "click" (not "click on") for commands, command buttons, option buttons, and list items. Avoid "choose", "select", "pick" for menu commands.
Select and Clear
Use "select" for check boxes, drop-down items, and file paths. Use "clear" for unchecking boxes. Use "remove the checkmark" for toggle commands.
Type or Select
For combo boxes, use "type" or "select". Use "enter" if no confusion is possible.
Points To
Use "points to" when describing submenu opening. User points to main menu command (submenu opens), then clicks the desired command.
UI Element Naming
Capitalization
Use sentence-style for headings and UI elements. Follow the UI exactly for labels and buttons. Do not capitalize generic identifiers.
- โ
Good: "the File menu", "click the Save button"
- โ Bad: "the File Menu", "click the Save Button"
Unavailable Commands
Refer to unavailable commands as "unavailable", not "dimmed", "disabled", or "grayed". Exception: Use "dimmed" or "grayed" when describing appearance.
Voice and Sentence Structure
Voice
Use active voice; minimize passive unless actor is irrelevant.
- โ
Good: "The system generates a report."
- โ Bad: "A report is generated by the system."
Sentence Starters
Avoid starting sentences with And, So, But.
Verbs
Replace vague verbs with precise ones: configure, select, deploy, generate, create, delete, update, enable, disable.
Lead-in Phrases
Remove redundant lead-in phrases.
- โ "In order to" โ โ
"To"
- โ "You have the ability to" โ โ
"You can"
- โ "It is possible to" โ โ
"You can"
Pronouns and Articles
Use optional pronouns and articles to clarify structure for global audience.
- โ
Good: "Inspect the database to ensure that all tables were correctly migrated."
- โ Bad: "Inspect database to ensure all tables were correctly migrated."
Inverted Pyramid Style
Give conclusion first. Put key information at start. Users should know whether to keep reading within first sentence.
Accessibility Standards
Headings
Heading levels should not skip. Headings must be descriptive and keyword-rich.
Links
Link text must be descriptive and make sense out of context. No "click here", "read more", "this link".
- โ
Good: "See the [Installation Guide] for system requirements."
- โ Bad: "Click [here] for more information."
Images
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.
Color
Avoid conveying meaning by color only. Add textual cues (e.g., "Required fields are marked with an asterisk (*) and appear in red.").
Tables
Ensure table headers use proper markup with scope. Provide caption or surrounding text explaining purpose.
Writing for Humans and AI Chatbots
Page Structure
Structure pages clearly with headings and accessible tables. Both humans and chatbots handle long pages if well-structured.
In-Context Links
Use in-context links with short explanations before or after. Helps chatbots understand purpose.
- โ
Example: "To configure and use webhooks, see [Working with webhooks], which provides step-by-step guidance."
Grouped Links
Group related links under clear headings. Prevents clutter and improves readability.
Table of Contents
Use clear, descriptive headings. Standardize terminology. Include keywords for user queries and AI searchability.
Content Accuracy
Ensure accuracy. Both humans and chatbots detect inaccuracies, destroying trust when users are already frustrated.
FAQ Content
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
Glossary content serves both humans and chatbots. Definitions can start with or without the term. OK to define collocations as ", ".
Localization Readiness
Time and Date References
Expand ambiguous time references. Spell out month names; use 24-hour time.
- โ
Good: "January 2025 release"
- โ Bad: "Q1 release"
Language
Avoid idioms and slang. Avoid contractions in UI labels. Use language understood by English speakers worldwide.
Pronouns
Avoid singular "they"; restructure for plural.
- โ
Good: "Users can configure their settings."
- โ Bad: "A user can configure their settings."
Latin and Non-English Words
Avoid Latin and non-English words. Use English equivalents:
- โ
"for example" instead of โ "e.g."
- โ
"that is" instead of โ "i.e."
- โ
"namely" instead of โ "viz."
- โ
"therefore" instead of โ "ergo"
- โ
"by/through/using" instead of โ "via"
- โ
"and so on" instead of โ "etc." (except space-limited contexts)
Sentence Structure
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.
Articles and Punctuation
Use optional articles and punctuation to clarify structure for localization.
Modifier Stacks
Avoid modifier stacks. If noun phrases exceed 3 words, rewrite.
Voice and Mood
Prefer active voice and indicative mood. Use imperative in procedures.
Elements to Avoid
Images
Do not use titles unless necessary.
Prerequisites
Do not use bullet lists for a single prerequisite; use plain text.
FAQ and Chatbot-Only Content
Avoid FAQ sections and content created solely for chatbots. Write for humans first; well-structured content serves all audiences.
Legal and Product Naming
Qlik Brand Name
First occurrence: Qlikยฎ. Subsequent: Qlik.
Usage
Use Qlik as adjective, not possessive.
- โ
Good: "Qlik Sense platform"
- โ Bad: "Qlik's platform"
Product Names
Preserve official product/component names exactly. Do not coin abbreviations. Consult terminology committee for new terms. Use same terms across product, documentation, and marketing.
Quality Gates Before Delivery
Before considering content complete, verify:
