Creating a documentation article

Create a documentation article that helps a reader complete one task, then save, review, and publish it on your website. This guide covers writing a single article and checking that readers can find and use it.

Before you begin

You need access to Site → Docs and permission to create or edit content. If the page is missing or the controls are disabled, see Why can’t I see or edit a feature?.

Have these ready:

• One reader goal. For example, “Download your invoice” is more useful than “Billing information.” Search your existing docs first so you can improve an existing answer instead of creating a duplicate.
• A verified procedure. Try the task yourself using the same permissions and setup your readers will have. Record the exact control names and what successful completion looks like.
• Any requirements. Identify the account role, enabled feature, subscription, file, or information the reader needs before starting.
• Safe examples and media. Use sample details and remove private information from screenshots. Make sure readers can open any linked files.

Keep each article focused. Link to a separate guide for a prerequisite or a different task instead of repeating a long walkthrough. If you already have Markdown files, use Importing Markdown documentation to bring them in as drafts, then review them using this guide.

Create the draft and choose its address

1. Open Site → Docs and select New doc. To improve an existing article, use its edit action in the list instead.
2. In Write, enter a specific Title, such as “Downloading your invoice.” This becomes the article’s main heading.
3. Check the Slug beside the docs/ prefix. For example, billing/download-invoice gives the article the path /docs/billing/download-invoice. Enter only the part after /docs/, not your full website address.
4. Use lowercase words separated by hyphens. A slash can separate related topics, as in the example above. Choose an address you can keep after publication.
5. Add your opening summary and initial instructions in Article body, then select Save draft. Wait for the saved confirmation before leaving.

The slug initially follows the title. Once you edit the slug yourself, later title changes do not replace your custom address. Check both fields before the first save; a nested address does not by itself place the article under a matching sidebar section.

Save draft saves your work without publishing it. If you are editing an already published article, readers continue seeing the published version until you select Publish changes. Browser recovery can help with an interruption, but it does not replace saving your draft.

Write an article readers can follow

Open with one or two sentences explaining the outcome and who the instructions are for. Put prerequisites before the first action, especially if the reader needs an administrator or another service.

Use a structure like this:

• Before you begin: access, setup, and information the reader needs.
• Do the task: numbered steps in the order the reader should follow them.
• Check the result: the message, screen, file, or public page that confirms success.
• Troubleshooting: likely symptoms, what to check, and what to do next.
• Related guides: a few useful next steps or prerequisites that are already published.

Name the button or field the reader should use. Prefer “Select Save draft” to “Save your changes.” If a step affects a live page or removes something, explain the effect before the action. Keep optional steps clearly marked.

Format the body

The toolbar adds Markdown formatting to your text:

• Use the Paragraph menu to choose Heading 2 for main sections and Heading 3 for subsections. The title already provides the main page heading, so do not repeat it as Heading 1 in the body.
• Use Numbered list for a sequence and Bulleted list for independent options or checks. Leave a blank line before and after a list.
• Use Bold for control names and Code for commands, filenames, or values the reader must enter exactly.
• For a link, select meaningful text and choose Link, then replace the example address in the inserted Markdown. Test the finished link; do not leave https://example.com as its destination.
• Keep paragraphs short. Use tables only when a compact comparison is easier to read than a list.

You can also paste Markdown directly into Article body. A section heading looks like ## Check the result; a link looks like [Read the guide](/docs/your-guide). Replace example paths with real, published destinations.

Select Preview in the body toolbar to check the formatted text. Select Edit to return to writing. This preview shows the body you are editing; it does not save or publish the article, and it is not a check of the full public page or sidebar.

Add images or downloads when useful

Place the cursor where the media belongs, then select Add Media. Upload a file or search the library and choose an asset. Images insert as images; other files insert as links.

Check the inserted description or link text. For an image, the text inside ![description](address) should explain the relevant content instead of repeating a filename. For a download, name the file’s purpose and format. Include the essential instructions in text so the reader does not have to interpret a screenshot alone.

Review file access before publishing. A file that opens for you as an administrator may still be unavailable to a visitor. See Uploading and organizing media and Fixing blurry images, failed uploads, or missing media.

Add a summary and organize the article

1. Open SEO and write Summary for cards and feeds. Describe what the reader will accomplish in a short sentence or two.
2. Check the Search result and Shared link previews. Customize Search headline or Search description when needed. The description can use your summary, and an empty summary can fall back to the search description or opening body text.
3. If you provide a Social image, use an image address that visitors can access. Keep Show this page in search results enabled if you want the article eligible for search engines. Turning it off is not a way to make confidential content private.
4. Open Taxonomy and enter an existing Category when it fits. Match its spelling so the docs index does not split similar topics into separate categories.
5. Add a few relevant Tags. Select the intended existing suggestion or new-tag option, and check that each chosen tag appears as a chip.
6. Return to Write, add a short Change Note describing the revision, and select Save draft.

Check sidebar placement separately

New articles start in the default Getting Started section. The basic editor does not expose the product, sidebar section, or order fields. Changing Category alone does not move an article out of an explicitly assigned section.

Before publishing into an established docs collection, arrange its placement with the person who maintains your documentation. If your site’s assistant has docs-editing access, you can ask it to match a neighboring article’s product and section and place the new article after it. Identify both articles by their exact paths and say to save the navigation change as a draft without publishing. Reopen the article afterward to review the saved version before making further edits.

Use Organizing your documentation navigation for exact requests, ordering, nested articles, and aliases. Ask for the article to remain visible in the docs navigation and searchable unless you have a specific reason to hide it. Hiding a sidebar link or excluding an article from search does not restrict access to its public address.

Review and publish

1. Follow the finished instructions from beginning to end. Check prerequisites, exact labels, examples, links, and the success check. Remove working notes, unsupported claims, and unfinished sections.
2. Use the body Preview to inspect headings, lists, code, and images. Check SEO and Taxonomy, then save the final draft.
3. If you want AI feedback and the feature is available, open Draft review in the AI co-author panel and select Run review. Assess each suggestion against the real workflow before applying it. Resolve any publishing blocker by fixing it or dismissing it only when you have verified it is incorrect. Save and review again after substantive changes.
4. Inspect the complete saved page before release. Ask your site administrator or an assistant with docs access for a saved preview of the latest draft. Check the article at desktop and mobile widths. If you edit afterward, get a fresh preview so you are reviewing the version you intend to publish.
5. When the article and its placement are ready, select Publish. For an existing live article, select Publish changes. These actions publish immediately; do not use them just to inspect a preview.
6. Wait for the publication confirmation. If Cedros reports that newer edits still need saving, review and save those edits before publishing again. Do not assume changes typed during publication were included.

AI feedback is optional and does not replace checking the instructions yourself. Follow Using AI to draft and review content for writing requests, suggested replacements, review findings, and recovery. For more about drafts, saved previews, and the live version, see Understanding drafts, previews, and publishing.

Check the published article as a reader

Return to Docs and use the article’s view action, or open its public address. Also check in a private browser window or an appropriate reader account so your administrator access does not hide a problem.

Confirm that:

• The public title and body match the version you approved.
• The docs index and sidebar place the article in the intended category and section, with a useful navigation label.
• Searching your docs for its title or main task finds it when search is enabled.
• Heading links land on the right section, and related links and downloads open the intended destinations.
• Text, lists, images, and any tables are readable on both a phone and desktop.
• A reader with the stated prerequisites can complete the task and recognize the result.

Your site’s access mode still applies. Publishing an article does not make a private or gated website publicly accessible. Search engines may also take time to discover a new page; publication is not a guarantee of an immediate search listing.

Troubleshooting

The address is already in use

Search the Docs list for the existing article. Edit that article if it answers the same question, or choose a different slug for a distinct task. Do not delete another article just to reuse its address. If the article is already public, coordinate an address change and redirects before changing shared links.

The formatting looks wrong

Switch from Preview to Edit and check blank lines, heading markers, list numbering, and paired formatting characters. Replace copied visual formatting with Markdown. Remove an extra Heading 1 if the title appears twice. Test wide tables and long code examples on a phone; use shorter examples or lists when they are easier to read.

Save or Publish is unavailable, or publication fails

Wait for an active save or publication to finish. Check any permission message and resolve the specific error shown. If Draft review lists a blocking finding, fix or dismiss it with a verified reason. Keep a saved draft while you resolve missing access or a release problem; an AI score alone does not prove publication succeeded.

The article is missing or shows an older version

Check that it is Published, then open its exact public path. A saved draft does not update the live article. If the path works but the sidebar or search does not show it, follow Fixing an article missing from navigation or search. If neither works, check the site’s access mode as well as publication status.

You need to correct the article later

Open its edit action in Docs, make the correction, preview it, and select Save draft, then Publish changes when ready. History lets you inspect saved revisions; restoring one makes it the current draft, so review it before publishing. If the article has a scheduled release, clear or coordinate that schedule before editing or restoring. Keep the existing address for ordinary wording changes.

Related guides

• Understanding drafts, previews, and publishing
• Customizing your blog and docs appearance
• Uploading and organizing media
• Controlling when your site is public
• Getting help and reporting a problem