29 users online | 29 Guests and 0 Registered

How do I properly format a KB article?


Introduction

Overview

The Scale Logic knowledge base runs on the phpMyFAQ platform, which offers a very comprehensive suite of formatting tools. As a result, it is can be a bit overwhelming to try and properly format an article. However, carefully selecting just a few of the formatting tools, each to be used for displaying a specific type of information, helps the knowledge base's overall readbability, consistency, and usability.

Conventions

This document will try to address both the WYSISYG defauly editor, as well as the "raw HTML" editor. Where exisitent, the corresponding HTML tags will be given alongside their respective GUI counterparts.

Formatting tools

Paragraphs vs line breaks - <p> vs <br />

Objective

A paragraph is meant to be more seperated from the content around it, while a line break is meant to be similar to the break created from a line wrapping around. Observe the difference between the following two examples

Example

Paragraphs

Paragraph 1. Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Paragraph 2. Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Paragraph 2. Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Line breaks 

Line break 1. Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.
Line break 2. Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.
Line break 3. Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Notice that by using paragraphs, rather than line breaks, a small bit of space is added between sections, creating a more pleasant reading experience.

Usage

Lorem ipsum

Headings

Objective

Headings help to create different sections of information within an article. This is especially nice with longer articles, as it helps to break the information and steps into more manageable pieces. For example, a new reader to the article may wish to get the full context of the process, while someone already familiar with it may only be looking to find a single step or command as quickly as possible. Headings, along with the rest of these formatting tools help greatly with this.

Example

When writing an article, simply select the text that you wish to be a heading, click the "Paragraph" drop-down, and choose the appropriate heading number. Below are examples of the 6 heading types, mixed with the standard "paragraph" style. Bear in mind that no additional spacing nor line breaks have been added below. Each heading brings a certain amount of leading and trailing space with it.

Heading 1

Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Heading 2

Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Heading 3

Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Heading 4

Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Heading 5

Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Heading 6

Lorem ipsum dolor sit amet, impetus oporteat no nec, recusabo assentior eu sed, in aliquam antiopam sit. Nec case evertitur suscipiantur eu. Ex qui alterum tractatos, case iriure id his, legere soluta latine et vim. Pro idque perfecto tacimates at, ea nam unum mediocrem.

Usage

This will be subjective to the size and complexity of the article. Generally, Heading 4 is a safe bet, as it bears the same weight as the article title.

Lists

Objective

Lorem ipsum

Example

  • Lorem ipsum
    • Lorem ipsum
    • Lorem ipsum
  • Lorem ipsum
    • Lorem ipsum
  • Lorem ipsum
  1. Lorem ipsum
    1. Lorem ipsum
    2. Lorem ipsum
  2. Lorem ipsum
    1. Lorem ipsum
  3. Lorem ipsum

Usage

Lorem ipsum

Code

Objective

There are many cases where you will wish to present technical information verbatim, and without 

Example

Lorem ipsum

Usage

Lorem ipsum

Code Sample

Objective

There are many cases where you will wish to present technical information verbatim, and without 

Example

Lorem ipsum

Usage

Lorem ipsum

Average rating:0 (0 Votes)

Login

Please enter your login name and password.

Sign up

Add question

Ask your question below: