How to Create a Knowledge Base Article

Knowledge base articles are the individual guides, answers and instructions that visitors read on your website.

SoftwareRoad Knowledge Base keeps these articles separate from normal WordPress blog posts, making it easier to organise product documentation, support guides and troubleshooting information.

Open the article editor

To create a new article:

1. Sign in to your WordPress dashboard.
2. Open Knowledge Base > Add Article.
3. Enter the article title.
4. Add the article content.
5. Choose a knowledge base category.
6. Add an excerpt and any images you want to use.
7. Preview the article.
8. Select Publish when it is ready.

The editor works in a similar way to the normal WordPress page and post editor.

Choose a clear article title

The title should tell visitors exactly what the article will help them do.

Good article titles include:

• How to Install SoftwareRoad Knowledge Base
• How to Activate Your Product Key
• How to Create a Knowledge Base Category
• Fix Licence Details Not Recognised
• How to Change the Knowledge Base Colours

Avoid titles that are too vague.

For example, Licence Help does not explain the exact problem being covered. A title such as How to Fix an Inactive Knowledge Base Licence is much clearer.

Clear titles also help your WordPress knowledge base search return more useful results.

Write the article content

Use the main WordPress editor to write your instructions.

You can add:

• Paragraphs
• Headings
• Numbered steps
• Bullet points
• Images
• Videos
• Buttons
• Links
• Tables
• Code examples
• Notices or callout boxes supported by WordPress

Try to keep each article focused on one task or question.

An article explaining how to activate the plugin should concentrate on activation. Other subjects, such as changing colours or viewing analytics, are usually better placed in their own guides.

Start with a short introduction

The first paragraph should quickly explain what the article covers.

For example:

This guide explains how to activate SoftwareRoad Knowledge Base using the purchase email address and product key supplied with your Monthly or Yearly subscription.

Visitors should be able to read the introduction and immediately know whether they have opened the right article.

Avoid long introductions that delay the actual instructions.

Add a “Before you begin” section

If the instructions require anything in advance, mention it near the beginning.

For example:

• Administrator access to WordPress
• An active subscription
• A product key
• A recent website backup
• An existing knowledge base category
• A published knowledge base page

This helps visitors prepare everything they need before starting the steps.

Use headings to organise longer articles

Break longer guides into clear sections using WordPress heading blocks.

Use Heading 2 for the main sections of the article.

Use Heading 3 for smaller sections that belong underneath a Heading 2.

For example:

• Heading 2: Activate the licence
  • Heading 3: Enter the purchase email
  • Heading 3: Enter the product key
• Heading 2: Fix common activation errors
  • Heading 3: Licence details not recognised
  • Heading 3: Licence server could not be reached

Avoid adding another Heading 1 inside the article content. The article title normally acts as the main Heading 1 for the page.

Using the automatic table of contents

SoftwareRoad Knowledge Base can create an article table of contents using the headings inside your guide.

The table of contents can use:

• Heading 2
• Heading 3
• Heading 4

This makes longer articles easier to browse because visitors can jump directly to the section they need.

Use meaningful heading names rather than headings such as:

• More Information
• Other
• Next Step

A heading such as Fix Licence Details Not Recognised gives the visitor a much better idea of what the section contains.

The table of contents can be displayed above the article or in the article sidebar, depending on your plugin settings.

Add numbered steps

Use a numbered list when the visitor needs to complete actions in a particular order.

For example:

1. Open the WordPress dashboard.
2. Select Knowledge Base > Settings.
3. Open the Design tab.
4. Change the primary colour.
5. Select Save Changes.

Keep each step focused on one action where possible.

If a step needs a longer explanation, add it underneath the numbered instruction rather than trying to fit everything into one sentence.

Use bold text for menu names and buttons

Bold text can make WordPress menu options and buttons easier to spot.

For example:

• Open Knowledge Base > Settings
• Select Save Changes
• Choose Upload Image

Avoid making entire paragraphs bold. Too much bold text makes the important parts harder to notice.

Add screenshots where they help

Screenshots can make settings and more complicated instructions easier to follow.

A useful screenshot should show:

• The relevant setting
• The button that needs to be selected
• The part of the screen being explained
• Enough surrounding information for the visitor to recognise the page

Crop out unrelated areas where possible.

Also make sure screenshots do not show:

• Complete product keys
• Customer information
• Private email addresses
• WordPress passwords
• Payment details
• Other sensitive account information

Images should support the written instructions rather than replace them completely.

Select a knowledge base category

Find the Knowledge Base Categories section in the article editor.

Select the category that best matches the article.

For example:

• Installation guides could go in Getting Started
• Product key guides could go in Licence and Subscription
• Colour and layout guides could go in Customisation
• Error solutions could go in Troubleshooting

Categories help organise the homepage, category pages, breadcrumbs and article recommendations.

Can an article use more than one category?

An article can be assigned to more than one category, but this is not always necessary.

Using several categories may cause the same article to appear in more than one part of the knowledge base.

For most articles, choose the single category that best matches the main subject.

Add another category only when the article genuinely belongs in both sections and the repeated listing will be useful to visitors.

Add an article excerpt

The excerpt is a short summary of the article.

It may appear in:

• Knowledge base search results
• Category pages
• Article lists
• SEO descriptions

A useful excerpt should explain what the visitor will learn without repeating the full article title.

For example:

Learn how to upload, install and activate SoftwareRoad Knowledge Base through your WordPress dashboard.

Keep it short and easy to understand.

If you do not add a custom excerpt, WordPress or SoftwareRoad Knowledge Base may use part of the article content instead. Writing your own excerpt gives you more control over how the article is described.

Add a featured image

You can add a featured image using the normal WordPress Featured Image option.

Depending on your SoftwareRoad Knowledge Base settings, the featured image can appear near the top of the article.

Featured images can also be useful when an article is shared on social media.

Choose an image that relates to the article and is clear at different screen sizes.

Before uploading it:

• Use a descriptive filename
• Compress the image
• Add useful alternative text
• Avoid uploading an unnecessarily large file

Add an article icon

SoftwareRoad Knowledge Base allows each article to have its own Bootstrap icon.

Enter a supported icon class in the article icon field.

For example:

bi-file-text

Other examples include:

• bi-download for installation guides
• bi-key for licence articles
• bi-gear for settings
• bi-palette for design guides
• bi-tools for troubleshooting
• bi-question-circle for help articles

The icon class must include the bi- prefix.

Add a custom article image

You can upload a custom image to use in place of the Bootstrap article icon.

Choose an image from the WordPress Media Library or upload a new file.

When both an article icon and custom image are set, the custom image takes priority.

Use clear, simple graphics that remain easy to recognise when displayed at a smaller size.

Mark an article as unlisted

SoftwareRoad Knowledge Base includes an unlisted article option.

An unlisted article remains available through its direct URL, but it is removed from the normal public article listings.

An unlisted article will not normally appear in:

• Knowledge base search
• Category article lists
• Popular Articles
• Related Articles
• Recommended Articles
• Knowledge base sidebars
• The WordPress XML sitemap

It will also receive a noindex instruction for search engines.

This can be useful for:

• Customer-specific instructions
• Temporary documentation
• Guides shared through a private link
• Articles that are not ready to be promoted publicly
• Support instructions intended for selected users

An unlisted article is not password protected. Anyone with the direct URL may still be able to open it.

Use WordPress privacy or password protection if the content must be properly restricted.

Preview the article

Before publishing, select Preview in the WordPress editor.

Check:

• The article title
• Paragraph spacing
• Headings
• Numbered instructions
• Images
• Links
• Category
• Table of contents
• Sidebar
• Featured image
• Reading time
• Helpful voting
• Social sharing
• Recommended article

Only the features enabled in your SoftwareRoad Knowledge Base settings will appear.

Previewing is particularly useful for spotting large images, broken links and headings that do not look right.

Publish the article

When the article is ready:

1. Select Publish.
2. Review the publication settings.
3. Confirm the publication.

The article will receive its own public URL.

A typical article address may look similar to:

example.com/knowledge-base/article-name/

The exact URL depends on the article URL base configured in the plugin settings.

View the published article

After publishing, select View Article.

Check the article as a visitor would see it.

Make sure that:

• The article opens without an error
• The correct category appears
• Breadcrumbs are correct
• The back link returns to the knowledge base
• The table of contents links work
• Images load correctly
• Links open the intended pages
• The layout works on mobile

You should also test the article while signed out of WordPress, especially if caching is enabled.

Check the category page

Open the category assigned to the article.

The new article should appear in the category list with its title and excerpt.

If it does not appear, check that:

• The article is published
• The correct category is selected
• The article is not unlisted
• The website cache has been cleared

Test the search

Open the main knowledge base page and search for part of the article title.

You can also search for an important phrase used in the content.

Confirm that:

• The article appears in the results
• The excerpt makes sense
• Selecting the result opens the article
• The title clearly matches the search

If the article is difficult to find, consider adding the wording visitors are likely to use to the title, excerpt or main content.

Add useful internal links

Where it makes sense, link to another knowledge base article that helps the visitor complete the next step.

For example, an installation guide could link to the activation guide after the plugin has been installed.

Use descriptive link wording such as:

Learn how to activate SoftwareRoad Knowledge Base

Avoid unclear links such as:

Click here

SoftwareRoad Knowledge Base also includes an automatic article links feature that can link the first use of selected words or phrases.

Check the article SEO

If the built-in SEO features are enabled, SoftwareRoad Knowledge Base can use the article title, excerpt, featured image and content to create useful search engine information.

Before publishing, check that:

• The title clearly describes the subject
• The excerpt works as a short description
• The article answers the question promised by the title
• Headings use clear wording
• Images have useful alternative text
• The article URL is short and understandable

Do not force the same keyword into every paragraph. Write naturally and use wording that helps the visitor.

Update the article when things change

Documentation should be reviewed when the product, setting or process changes.

To update an article:

1. Open Knowledge Base > All Articles.
2. Select the article.
3. Make the required changes.
4. Preview the updated version.
5. Select Update.

The article’s modified date can be used by the Recently Updated section.

Regular updates also help prevent customers from following instructions that are no longer correct.

Save an unfinished article as a draft

You do not need to publish an article immediately.

If it is not ready:

1. Add the title and any completed content.
2. Select Save Draft.
3. Return to it later through Knowledge Base > All Articles.

Draft articles do not appear on the public knowledge base.

This is useful when screenshots, checks or further information still need to be added.

Schedule an article

WordPress may also allow you to schedule the article for a future date.

Choose the publication date and time from the article settings, then select Schedule.

The article will remain unavailable to normal visitors until the scheduled publication time.

WordPress scheduled tasks must be working correctly for scheduled publishing to take place.

The article does not appear publicly

If the article is missing, check that:

• Its status is Published
• It is not still a Draft
• It is not in the Trash
• It is assigned to a category
• It is not marked as unlisted
• Your SoftwareRoad Knowledge Base licence is active
• The public knowledge base is available
• The website cache has been cleared

Also check the article URL directly.

The article returns a 404 error

If the article has been published but returns a page not found error:

1. Open Settings > Permalinks.
2. Select Save Changes.
3. Clear the website cache.
4. Open the article again.

You should not need to change the selected WordPress permalink structure.

Also check that another page is not using the same slug as the SoftwareRoad Knowledge Base article URL base.

The article is not appearing in search

Check that:

• The article is published
• The article is not unlisted
• Search is enabled
• The search wording appears in the title, excerpt or content
• The search contains at least two characters
• Your licence is active
• JavaScript and AJAX requests are working

Try searching for an exact word from the article title.

Article publishing checklist

Before finishing, check that:

• The title clearly explains the article
• The introduction explains what the visitor will learn
• The instructions are in the correct order
• Headings break up longer sections
• The article has a suitable category
• A useful excerpt has been added
• Images do not show private information
• Links have been tested
• The article has been previewed
• The public page works on desktop and mobile
• The article appears in its category
• The article can be found through search
• The article is not accidentally marked as unlisted

Your knowledge base article is now published and ready for visitors to use.