• Improve this Doc

    Show / Hide Table of Contents

    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.

    Links to web pages

    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 Knowledge Centre articles

    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.

    Generated by DocFX
    Back to top
    © UKCloud Ltd, 2019. All Rights Reserved.
    Privacy Policy. Terms of Use. Contribute.