Creating and editing an article

Ref: C15 · Track: Knowledge Base Admin · Time to complete: ~6 min

Why this matters

This is the core thing a Guide user does. Everything else — structure, review, publishing — orbits around the act of writing or editing an article well. This walkthrough assumes you know nothing and want to get good quickly.

Starting a new article

From Guide admin: 1. Click Add article. 2. Choose the category and section it lives in (see C02 for structure). You can move it later. 3. Give it a clear, searchable title. 4. Start writing.

Or: from the book view, open the section, click New article inside that section. Same result, but the section is pre-set.

The editor layout

Body (left, main area): the article content. Rich text editor with formatting toolbar.

Right sidebar: article settings — - Status (Draft / Awaiting review / Ready / Published — see C06). - Reviewer. - Managed by / Visible to (see C12). - Labels (see C16). - Template (theme-specific; see C17). - Attachments.

Top bar: Save, Publish, Preview (see C04), History (see C09), more actions.

Writing the body — basic formatting

The toolbar covers: - Headings (H2, H3, H4). Use H2 for top-level sections, H3 for subsections. Don't skip levels. - Bold / italic / underline — use sparingly. - Lists — bulleted or numbered. Great for steps. - Quote — for verbatim quoted text or callouts. - Code — inline and blocks. - Tables — add, edit, resize. - Links — highlight text → link icon → paste URL.

The source-view toggle (<>) lets you drop into HTML when you need control the WYSIWYG won't give you.

Adding images

1. Click the image icon in the toolbar.
2. Upload from your computer (or drag into the editor).
3. The image uploads to Zendesk and renders inline.
4. Click the image to resize, add alt text, or set alignment.

Alt text is required for accessibility. Don't skip it.

Adding videos

Two ways:

Embed from YouTube / Vimeo / Wistia

Paste the embed URL into the editor; Zendesk expands it automatically.

Upload to Zendesk

Some plans allow direct upload. Smaller/short clips only; for longer training video, use a dedicated video host and embed.

Attachments

Downloadable files (PDFs, xlsx, zip) can be attached via the attachments section in the right sidebar. They render as download links at the bottom of the article.

Inserting content blocks and links to other articles

• Content block: Insert → Content block → pick (see C14).
• Link to another article: highlight text → link icon → either paste the article URL or use "Link to article" search.

Internal links help discoverability and SEO; use them liberally when referencing related content.

Saving, previewing, publishing

• Save draft: cmd/ctrl-S or click Save. Keeps the article in Draft or maintains a green dot (see C06) on a published article.
• Preview: see C04. Always preview before publishing — especially for mobile.
• Publish: makes the content live. Requires Ready-to-publish status for reviewed articles.

Editing an existing article

1. Open the article.
2. Make changes. The article is now in "saved edit with green dot" state (if published).
3. Preview.
4. Publish to make live.

History (C09) tracks every edit — you can always revert.

The anatomy of a good Zendesk article

Not a Guide rule, but an internal standard worth adopting:

1. Clear title — what someone would search for.
2. One-sentence summary — what this article covers. Customer knows instantly if they're in the right place.
3. Numbered steps where procedural; short prose where conceptual.
4. Screenshots for anything visual. Alt text on every one.
5. Related articles at the bottom — 2–4 links.
6. Last-reviewed or last-updated date — makes content feel current.

Gotchas

• Don't paste from Word or Google Docs directly. The embedded styling leaks in and breaks consistent formatting. Paste as plain text, then re-format.
• Mobile formatting. Tables wider than ~3 columns often look bad on mobile. Preview.
• Auto-save is partial. Large edits should be manually saved; don't rely on background autosave.
• Links to "internal" URLs break for customers. Make sure linked articles are visible to the same audience as the containing article.
• The editor has quirks. Switching between WYSIWYG and source view sometimes rewrites the HTML. Pick one mode per editing session.

Quick check — have you got this?

• You've finished writing a new article. What's the sequence before it goes live?
• You edit a published article and save. Can customers see the change?
• You paste a long quote from a Word doc. What should you do?

Related articles

• C02 — How the KB is structured
• C04 — Preview modes before publishing
• C06 — Review statuses and publishing rules
• C14 — Content blocks: reusable snippets
• C16 — Content tags vs labels