Write documentation articles

An article is a page of written documentation: a runbook, an onboarding checklist, or the answer to a question your desk gets every week. This page shows how to write one, publish it, keep it current, and see what changed between versions. An article you publish and make visible to end users also appears in the Outpost tray app on that client’s endpoints.

Before you begin

• You need the docs:write permission to create and change articles. docs:read is enough to read them.
• Decide where the article belongs. A client article sits under that client’s Documentation > Articles. On the MSP plan, a practice article is written once and read from every client.

Write an article

1. In the console, go to Documentation > Articles and select New article.
2. Optionally, in Start from a template, choose an article that someone has offered as a template. Outpost copies its body, summary, and labels. The title stays yours.
3. In Title, enter the title. Slug follows the title until you change it. The slug is the part of the address other people link to.
4. In Summary, enter one sentence. It shows in the article list and in search results.
5. In Status, choose Draft or Published. An article stays a draft until somebody publishes it.
6. In Visible to, choose Internal or Visible to end users.
7. In Scope, choose This client or Practice. A practice article is read from every client.
8. In Labels, enter labels separated by commas.
9. In Review every, enter the number of days between reviews. 0 means Outpost never asks.
10. Write the body in Markdown. The preview beside it is exactly what readers see. Use Source, Split, or Preview to choose the view.
11. Select Save.

While you write:

• Type @ to mention another record, such as a credential, an asset, or an endpoint. A mention becomes a link on the article’s Relations tab. A mentioned credential shows only its name. Readers open it to reveal it.
• Paste a table from a spreadsheet and it becomes a Markdown table. Merged cells are flattened, because Markdown tables cannot span columns.
• Paste from a word processor and the text is converted to Markdown.
• A fenced code block marked mermaid is drawn as a diagram.

Raw HTML is not stored. An article imported as HTML can be read but not edited. To change one, replace it with a Markdown article.

Publish an article

Open the article and select Publish. The Publish button shows only while the article is not published. To take an article out of circulation, open its Editing tab, set Status to Archived, and select Save.

Show an article to end users

An article that is both Published and Visible to end users appears under Help articles in the Outpost tray app on that client’s endpoints, where end users can search it. Drafts and Internal articles are never sent to the tray. One search returns at most 50 articles, and an article body longer than 256 KB is cut off with a note saying where it stops. See Tray.

Caution

Internal articles often name a client’s accounts and workarounds. Check what an article says before you make it visible to end users.

Keep an article current

Each article shows Review and Last checked under About this article on its Read tab.

• Review every sets how often the article comes due. When it does, it counts toward past review on the Documentation Overview and appears on Expirations as Article review.
• When you have checked that an article is still true, open it and select Mark as current. Outpost records your name and the date. An article nobody has checked shows Never checked in the list.

See what changed and restore a version

Every save writes a new version. Nothing in the history is deleted.

1. Open the article and select the Revisions tab.
2. Under Versions, select a version. Each one says why it was written, such as Created, Edited, Published, or Restored, who wrote it, and when.
3. Read What changed, which compares that version with the one before it. A comparison too long to finish says so and shows the start.
4. To bring that text back, select Restore version followed by its number. Restoring writes the text back as a new version.

Offer an article as a template

On the article’s Editing tab, select Offer this article as a template for new ones, then select Save. The article is then listed in Start from a template when someone writes a new article.

Verify

Open Documentation > Articles. Your article is listed with its status. If you set Review every, the Review column shows the next review date rather than Not scheduled. For an article visible to end users, open the Outpost tray app on one of the client’s endpoints and search Help articles for its title.

If something goes wrong

Symptom	Cause	Fix
A search in the article list finds nothing for a word you know is in the body.	The list’s search matches the title only.	Use the search bar at the top of the console, which searches inside articles.
An article does not appear in the tray.	It is a draft or Internal.	Set Status to Published and Visible to to Visible to end users.
The server would not store a construct.	The body contains something the server refuses, such as raw HTML.	Remove the named construct and save again.

Next steps

• Assets and asset layouts
• Track expirations
• Using the tray