qlik-writing-guidelines

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:

1. Writer's explicit instructions and provided source files/snippets
2. This skill content (Qlik-specific guidelines for all formats)
3. Microsoft Style Guide (adapted to Qlik rules; reference: https://learn.microsoft.com/en-us/style-guide/welcome/)
4. 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:

• Style rules applied (click, sentence-style UI, active voice)
• No ambiguous pronouns
• Lists and procedures structurally valid
• Accessibility standards satisfied
• Localization-friendly (no idioms, Latin terms, ambiguous time refs)
• Product and legal naming correct
• No format-specific issues (validate with markup-specific skill)
• All [ASSUMED] placeholders documented