UKCloud Knowledge Centre article template

The first thing in your article after the metadata should be the main article title. Use the following to help you decide on the title for your article

  • Titles (and all other headings) should be in sentence caps (that is, the first word should start with an uppercase letter and all other words should be all lowercase unless they are proper nouns)

  • Use a single # for the article title (and don't forget the space after the #)

  • How To Guide titles should start with How to and then a verb to describe the task described in the article, for example How to create a virtual machine.

  • Reference Guides should start with a noun if possible

Generally, you should not include any text below the article title, but should go straight to the first (Overview) heading. However, if the article is very short and does not require any subheadings, you can include the content directly below the article title.

Overview

The first section after the article title should be Overview and should provide an introduction to the purpose of the article.

Intended audience

For How To Guides, if appropriate, you can include an Intended audience subsection below the Overview section to indicate any particular access or permissions a user might need to complete the steps in the task described by the guide.

Further sections

Use additional sections to break the article up into manageable chunks to make it easier to read.

Section headings should be in sentence caps (that is, the first word should start with an uppercase letter and all other words should be all lowercase unless they are proper nouns).

In How To articles, you may just have a single additional section describing the task being described in the article -- you should use gerunds for the section headings (words ending in -ing). For example Logging into the OpenStack Horizon dashboard. If the article includes multiple tasks, put each task into its own section.

Reference Guides can include as many sections as necessary to keep the content easy to read. But don't use too many levels of subsections as it can be difficult for users to keep track of where they are if the subsections go too deep.

Bulleted lists

  • Bulleted lists

  • Look

  • Like this

    • with sub lists

    • if required

Numbered lists for How To Guides

  1. Numbered lists

  2. In a How To Guide

  3. Look

  4. Like this

    • you can include

    • bulleted lists

More useful markdown

Images

Markdown for images looks like:

![alt-text](images/image-filename.png)

The alt-text is read out by screen readers and provides a brief description of the image to help visually impaired users determine what the image is illustrating. Image files should be located in an images directory underneath the main product directory.

To link to a web page, use the following markdown:

<https://ukcloud.com/>

https://ukcloud.com/

To use descriptive text for the link, rather than just the URL, use the following markdown:

[UKCloud](https://ukcloud.com/)

UKCloud

Links to other articles for the same product look like:

[*topic-title*](topic-filename.md)

For example:

[*UKCloud Knowledge Centre guidelines*](other-ref-knowledge-guidelines.md)

UKCloud Knowledge Centre guidelines

Links to other articles for a different product look like:

[*topic-title*](../product/topic-filename.md)

For example:

[*Getting Started Guide for the UKCloud Portal*](../portal/ptl-gs.md)

Getting Started Guide for the UKCloud Portal

Tips, notes and warnings

Tips

A tip provides helpful, but not necessarily important, information.

Markdown:

> [!TIP]
> This is a tip, which provides helpful, but not necessarily important, information.

Looks like:

Tip

This is a tip, which provides helpful, but not necessarily important, information.

Notes

A note provides important information.

Markdown:

> [!NOTE]
> This is a note, which provides important information.

Looks like:

Note

This is a note, which provides important information.

Important notes

Important notes provide important information that requires particular attention.

Markdown:

> [!IMPORTANT]
> This is an important note, which requires particular attention.

Looks like:

Important

This is an important note, which requires particular attention.

Warnings

Warnings provide important information about something which could have significant implications if ignored.

Markdown:

> [!WARNING]
> This is a warning, which provides users with information about something which could have significant implications if ignored.

Looks like:

Warning

This is a warning, which provides users with information about something which could have significant implications if ignored.

Feedback

Each article should end with a feedback section that includes the following text:

If you have any comments on this document or any other aspect of your UKCloud experience, send them to products@ukcloud.com.