How to write a knowledge base article – Ehelp

Creating clear, helpful knowledge base (KB) articles is essential for supporting customers and internal teams. At Teleflora, we use Notion as our authoring tool and HelpKit to publish those articles to a customer-facing website.

This guide walks through how to structure, write, and enhance a knowledge base article in Notion, while ensuring it displays cleanly and correctly in HelpKit.

Why We Don’t Use H1 Headings

Before we start, an important rule:

Do not use H1 headings in Notion.

HelpKit does not display H1s in the table of contents (ToC) on the front-end. To ensure your article is easy to scan and navigate:

Start with H2 headings as your top-level sections

Use H3s and H4s for subsections

Rely on the page title as the “H1 equivalent”

Step 1: Start With a Clear Page Title

Your Notion page title acts as the article’s main heading.

Best practices for titles:

Be specific and action-oriented

Match what a user would search for

Avoid internal jargon if the article is customer-facing

Good examples:

“How to Update Delivery Preferences”

“Troubleshooting Order Status Issues”

“Understanding Delivery Time Windows”

Step 2: Structure Your Article Using Headings (H2–H4)

A strong structure helps readers skim and helps HelpKit generate a useful ToC.

Recommended Heading Hierarchy

Use headings like this:

H2 – Main sections

H3 – Subsections within a topic

H4 – Optional details or edge cases

Example structure:

H2: What This Feature Does
H2:Whento Use ThisOption
H2: Howto Update Delivery Preferences
  H3:Step1: Open theOrder Details
  H3:Step2:Select a Delivery Window
H2: Common Issuesand Tips

Tips for Headings

Keep headings short and descriptive

Avoid punctuation when possible

Write them so they make sense in the ToC alone

Step 3: Write Scannable, Helpful Body Content

Most users won’t read every word. Make your content easy to consume.

Use Short Paragraphs

Aim for 1–3 sentences per paragraph

Break up dense explanations

Use Bulleted and Numbered Lists

Notion renders lists beautifully in HelpKit and they’re ideal for:

Steps

Requirements

Options or variations

Example:

Orders must be submitted before the cutoff time

Delivery windows depend on florist availability

Fees vary by location

Use Plain Language

Write at a conversational, instructional level

Avoid unnecessary technical terms

Explain acronyms on first use

Step 4: Use Notion Callouts for Emphasis

Notion callouts are one of the best ways to highlight important information.

Common Use Cases

Warnings or limitations

Helpful tips

Notes about edge cases

Examples:

💡 Tip: Orders placed after 2 PM may be delivered the next business day.

⚠️ Note: Same-day delivery is not available on certain holidays.

Keep callouts concise—too many can overwhelm the reader.

Step 5: Add Visuals the Right Way

Images and visuals can dramatically improve understanding.

Best Practices for Images

Use screenshots only when they add value

Crop to the relevant area

Avoid tiny text or cluttered screens

Captions

If context isn’t obvious, add a short caption below the image explaining:

What the user is seeing

What they should do next

Step 6: Use Toggle Lists for Optional or Advanced Content

Toggle lists are perfect for:

FAQs

Advanced scenarios

Rare edge cases

Long explanations that not all users need

Examples:

“What if the customer requests a specific time?”

“Why is this option unavailable?”

This keeps the article clean while still thorough.

Step 7: Link to Related Articles

Help users continue their journey by linking to relevant KB articles.

When to Link

Related setup steps

Deeper explanations

Troubleshooting guides

Best practices:

Use descriptive link text

Avoid “click here”

Open links in the same tab (default behavior is fine)

Step 8: End With Helpful Closure

Wrap up the article with one of the following:

A brief summary

Next steps

A pointer to support if the issue isn’t resolved

Example closing:

If you’re still experiencing issues with delivery options, please contact support with the order number and delivery date.

Step 9: Final Quality Checklist

Before publishing, review your article:

✅ No H1 headings used

✅ Clear H2/H3 structure

✅ Headings appear correctly in the ToC

✅ Short paragraphs and scannable lists

✅ Callouts used intentionally

✅ Images are clear and relevant

✅ Links work and are helpful

Writing With the Reader in Mind

The best knowledge base articles:

Answer questions quickly

Reduce back-and-forth with support

Feel easy, not overwhelming

By combining Notion’s powerful writing features with thoughtful structure, you ensure your articles look great in HelpKit and genuinely help the people reading them.