On this page

Before you start#

You need the Create knowledge-base articles permission to write, and Publish knowledge-base articles to publish. If your role has the Manage knowledge base template, you have both. If you cannot see the New Article button, see Knowledge Base permissions.

This walkthrough takes about five minutes and ends with a live article you can verify from both sides.


Step 1 — Open the authoring surface#

  1. Click Knowledge Base in the left navigation. This opens the Library, your team's reading room.
  2. Click Manage articles at the top right.

You are now on the authoring surface. Choose the tab the article belongs under: Internal Articles, External Articles, or Specifications. If that tab is empty, you will see a message such as No internal articles yet and a Write your first article button — you can start from there instead of step 2.

Step 2 — Create the draft#

Click New Article. The draft starts as the type of the tab you are on:

Tab The draft starts
Internal Articles Set to Internal (members only)
External Articles Set to Portal (customers)
Specifications Filed in a category that holds specs, and set to Portal (customers)

If you have a category selected in the sidebar and it belongs on that tab, the new article is filed there straight away. Otherwise it starts Uncategorized, except on Specifications, where it goes into the first category in the tree that holds specs.

If no category holds specs, New Article is disabled on Specifications, and hovering it says Mark a category as holding specs first. To turn that on, see Creating a category.

Import from Formwork files the imported spec where New Article would, and is disabled in the same case. An imported spec is always set to Internal (members only), so unless it lands in a category that holds specs, or a subcategory of one, it is listed under Internal Articles. See Formwork requirements.

DevStride creates the draft immediately and opens it in the full-page editor. It is called Untitled article until you name it.

The draft is already saved

The article exists the moment you click the button — there is no unsaved, in-limbo state to lose. If you close the tab right now, the draft is waiting for you on the Manage list.

Step 3 — Write it#

Title — click the title field at the top and replace Untitled article. Keep it specific and phrased the way a reader would search for it. "Reset a forgotten password" beats "Password policy" if resetting is what people actually come looking for.

Summary — the field just under the title, marked Summary: one sentence shown under the title, takes one sentence (up to 500 characters) saying what the article is about. Readers see it under the title in the library and in the customer Help center. It is optional: leave it empty for no summary, or clear it to remove one. It saves with the title. If you can only comment on the article, the field is not shown.

Body — click into the editor below and write. It is the same rich-text editor used for item descriptions, so the formatting, keyboard shortcuts, and image pasting all behave the way you are used to. You can paste or drag images straight in.

Callouts — to make a passage stand out as a coloured box, put your cursor in it and choose a type from the Callout menu (the info icon beside the quote button in the toolbar): Info, Note, Tip, Warning, Caution, Danger or Success. Each type has its own colour. Choosing a type inside a quote turns that quote into a callout, and choosing another changes its type. Remove callout turns the box back into ordinary text. To give a callout a heading, start it with a line in bold. Readers see the same coloured boxes in the library and in the customer Help center. The Callout menu is only in the Knowledge Base article editor.

Watch the save indicator beside the title. It tells you exactly where you stand:

It says Meaning
Saved Everything is written to the server.
Saving... A save is in flight.
Title required The title is empty, so nothing is being saved. Type a title.
Save failed The last save did not go through. Check your connection; your text is still on screen.

Saving is automatic and debounced — it fires shortly after you stop typing, not on every keystroke.

Title required means you are not being saved

An article must have a title between 1 and 300 characters. While the title is blank, DevStride deliberately refuses to save the body rather than storing an untitled article. If you see Title required, give it a title before you write anything you would hate to retype.

Step 4 — File it into a category#

The right-hand rail is divided into panels — Status & lifecycle, History, Comments, Sharing, Audience, Organization, and (once published) URL. This walkthrough uses Status & lifecycle, Audience, Organization, and URL. History fills itself in as you work, recording who changed what and when — see Article history and restore. Comments holds your reviewers' feedback — see Article review comments. Sharing decides which members of your team can read, comment on, or edit the article; it starts open to the whole organization (or follows the category you file it in) — see Sharing articles and categories.

Click the Organization heading to open it, and set Category to where the article belongs.

If you have not built any categories yet, leave it alone — the article becomes Uncategorized, which is a perfectly valid home. You can file it later, and you can build your category tree once you have a sense of what you are actually writing. See Organizing with categories.

Fold, widen or hide the sidebar#

Each panel folds away under its heading. Status & lifecycle and Comments start open; the others start folded, and a folded panel still shows a short summary on its heading, such as the article's state, its latest change (Edited · 2 hours ago), who it is shared with (Everyone can comment), its visibility or its category. Comments always shows how many threads are open, as a red badge on its heading. Click a heading to open or fold that panel. DevStride remembers which panels you opened or folded, in this browser, for every article you edit.

Drag the sidebar's left edge to make it wider (for long comment threads) or narrower (for more room to write). Drag it narrower still and it hides, leaving a small tab at the right edge of the window: click the tab to bring the sidebar back at the width it had. Clicking pinned words in the article, or following a link to one of its comments, brings it back too.

Step 5 — Choose who it is for#

Open the Audience panel of the rail and set Visibility:

  • Portal (customers) — customers may read it, once it is published.
  • Internal (members only) — only your team, ever. You will see the hint "Internal articles never appear on your customer portal."

The setting starts from the tab you created the draft on. If it is wrong for this article, change it now rather than after publishing. This setting and the article's category together decide which tab lists it.

Check the category, not just the article

If you filed the article into a category whose audience is Internal, the article stays hidden from customers no matter what you set here. That is intentional, and the category tree shows an Internal badge so you can spot it. The audience page explains the rule in full.

If you want the article restricted to particular customer companies rather than all of them, click Edit next to Companies and choose them. Leave it as All companies if everyone should see it.

Step 6 — Publish#

Click Publish in the Status & lifecycle panel.

The first time you publish an article, DevStride asks you to confirm and shows the URL it is about to create:

Publish article This article will be published with the URL slug "reset-a-forgotten-password". If that slug is already taken, a numbered variant (e.g. "reset-a-forgotten-password-2") is used instead.

Click Publish to confirm.

Three things happen:

  1. The state chip changes to published and a Published {date} line appears.
  2. The article gets a permanent URL slug — shown in a new URL panel in the rail.
  3. It becomes readable immediately. There is no build, cache, or republish step.

The slug is minted once and then it is yours

The slug comes from the title, but it is frozen at first publish. Renaming the article later does not change the URL, so links you have shared keep working. You can change it deliberately with Change URL — see The article lifecycle and URLs.

Step 7 — Confirm your readers can see it#

This is the step people skip, and it is the one that catches mistakes.

Check the team side. Click View in library beside the state chip — it appears once the article is published — to read it exactly as a teammate would. (Or click ← Manage articles, then Browse, and find it under its tab.) If you marked it internal, it carries an Internal badge — that badge is your confirmation that customers are not seeing it. Which teammates can read it is shown in the editor's Sharing panel.

Check the customer side. Back in the editor, open the URL panel and look under the slug. If you see:

Live on your customer portal

then the article genuinely is reachable by customers — it is published, marked for the portal, and no category is hiding it. If that line is absent on an article you meant to publish externally, something is blocking it. Work through Who can see an article to find which of the three gates is closed.

Why there is no View on portal link

A portal URL belongs to a company (/portal/<company-slug>/kb/<article-slug>). An article shared with several companies therefore has several addresses and no single canonical one, so the editor tells you it is live rather than linking you somewhere arbitrary. To see exactly what a customer sees, open the portal as that company.


What to do next#

Keep writing. Repeat steps 2–6. Once you have a handful of articles, patterns emerge and you will know what your categories should be.

Then organize. Build the category tree around the articles you actually wrote, not the ones you imagined writing. See Organizing with categories.

Retiring something later. Use Unpublish to pull an article back to draft while keeping its URL reserved, or Archive to retire it for good. Neither deletes anything.

Quick reference#

To do this Go here
Write a new article Manage articles → the tab it belongs under → New Article
Change the title, summary or body The article editor (saves automatically)
Add a coloured callout box Editor toolbar → Callout → choose a type
File it in a category Editor rail → Organization → Category, or drag the row onto a category
Make it customer-facing Editor rail → Audience → Visibility
Limit it to certain companies Editor rail → Audience → Companies → Edit
Publish it Editor rail → Status & lifecycle → Publish
Change its URL Editor rail → URL → Change URL
See who changed it, or go back a version Editor rail → History → Preview → Restore this version
Choose which teammates can read, comment on, or edit it Editor rail → Sharing → Share
Read or answer review feedback Editor rail → Comments
Take it down Unpublish (back to draft) or Archive (retire)
Powered by DevStride