Skip to end of metadata
Go to start of metadata

For single-document organization and total Knowledge Base organization, page structure is important. Page sections should be well defined and like topics should be grouped together. The easiest way to provide good page structure is to provide clear headings for topics within your article. A table of contents on long pages, internal links, and external links are also components which contribute to good page structure. When creating Knowledge Base articles, the way the page will be organized in the overall Knowledge Base, as well as how users will search for the article, is incredibly important to keep in mind.

Heading structure

Long documents should include several levels of headings to help organize the entire piece and guide users through the table of contents. Headings will differ slightly depending on the type of article you are creating. 

General rules for headings

Typically, the highest level of heading you will use is Heading 2. 

As a rule, major headings should follow a task-oriented approach and include gerunds. Heading examples: How to Download and Install Microsoft Word

Subsequent levels of headings should follow a similar task-oriented approach or a "to [verb] the [program]" approach. 

Headings should follow the set stylesheet for clarity and consistency within the table of contents. Because headings will help users identify what topics they need to read further, having clear and concise headings is important in delivering the best instruction to the user. Good headings equal less time searching for a topic; this saves the user time, and they will be happier as such.

All headings except the page title should follow sentence case, which means that the first letter of each word is lowercase unless it is a proper noun. For example: How to download and install Microsoft Word.

How-to

For How-to articles, two of the major headings (Heading 2) will always be Step-by-step guide and Related articles. If the page includes content that does not follow steps, it may fall under a different Heading 2. However, consider whether such content would fit better in a Reference article. Under the Step-by-step guide heading, you may need to include multiple sections for different sets of steps. Use Heading 3 for these. If you need further subdivision, use Heading 4 followed by Heading 6 (not Heading 5). Lower-level headings should be action-oriented. For example, Installing Word on a Windows computer or To install Word on a Windows computer. Whichever you choose, be consistent throughout the article.

Troubleshooting

For troubleshooting articles, each Heading 2 should be the name of a problem. For example, Problem - I cannot hear any audio. If the page only includes one problem, the heading only needs to say Problem. Solutions should be presented in panels, such as the one below.

Solution

This is an example of a panel. To add a panel, follow the steps below:

  1. In Edit mode, click the Insert (+) button from the toolbar, then select Other macros.
  2. Using the search bar at the top, type panel.
  3. Click Panel.
  4. Under Panel Title, type Solution.
  5. Click Insert.

If a problem has multiple solutions, title them Solution 1, Solution 2, etc.

Reference

For Reference articles, you have a little more freedom in how to structure your page. However, be sure to follow the general rules for headings discussed above, and organize the page in a way that will be easy for readers to follow.

Table of contents structure

A good table of contents is built from good headings. Having one will assist users in finding the specific information they need. In addition, they are simple to include in a wiki page. Very short articles do not necessarily need a table of contents; very large articles do.

Only include a table of contents if you have at least two headings to include in it.

For How-to articles, you will usually place a table of contents right under the Step-by-step guide heading. When you have the Insert 'Table of Contents' Macro open, set the Minimum Heading Level to 3 and the Maximum Heading Level to 4. If you have additional Heading 2s (other than Step-by-step guide and Related articles), include the table of contents after the introductory text of the article, and set the Minimum Heading Level to 2.

For Troubleshooting articles, place the table of contents under the introductory text. When you have the Insert 'Table of Contents' Macro open, set the Minimum Heading Level and Maximum Heading Level to (unless you have a good reason to include further heading levels).

For Reference articles, place the table of contents under the introductory text. When you have the Insert 'Table of Contents' Macro open, set the Minimum Heading Level to 2 and the Maximum Heading Level to (unless you have a good reason to include further heading levels).

Links structure

Creating links to sections on a specific wiki page, to other pages within the wiki, or to outside resources is important to organization. Creating anchors on a wiki page can help you write less on a given page as you can provide "jump backs" to previous sections. Internal linking can also be used to direct a user to a specific section on a different wiki page.

Page names

When naming pages, do not choose names that will be obscure. Stick to standard names and names given by software companies, developers, etc. If the subject/idea has a proper name then you should try and make that the page name. For instance, “Adobe Acrobat Professional 9” is often referred to as simply "Acrobat Pro” or “Acrobat" but you should make the page name “Adobe Acrobat Professional 9” because this is the actual name. Sometimes it's not clear what the real name of the place/thing/idea you're making a page for should be. In these cases of confusion, just make a decision as to what the page name should be, then make note of the alternative possibilities in the page itself. Referring to the other possible names allows people to do searches and find the page under any of the possible names. An example of this is “PaperCut”, which is also “BearPrint”. It's not clear what the name of the page should be, so a simple reference to the other name (somewhere in the page, probably toward the beginning) fixes this and allows people to find it in a search. Also utilizing the proper Label will categorize the page and aid in searching. Searching is very important, especially for people who don't use the site regularly.

Different types of articles should follow different naming conventions.

All How-to article titles should begin with How to.

All Troubleshooting article titles should being with Troubleshooting.

Reference articles should NOT typically include "reference article" in the title. Simply follow the general page name suggestions discussed above.

Labels

Labels are very important for categorizing and searching. Therefore we have a standard set of page labels to be included on each page. Labels are used to categorize pages, not to repeat a page title. Searching in Confluence is aggregated by page title first, then labels, then document contents. The following are Knoweldge Base labels. Additional label conventions may be used by Private Spaces.

Never use two-word labels, as they are added as two separate label entries. For example "In Progress" is added as a label for "In" and a label for "Progress", which is not helpful when it comes to searching. If you absolutely must use a two-word label, type it as one word by inserting a hyphen between words (i.e. in-progress).

Only use the labels below in the Knowledge Base. If you have a label suggestion, please email Aubrey Larimore Vargas to determine whether it should be added to the following list.

Labels by parent page

Parent PagesLabels
About Expertsexperts*
Account and Accessaccount*
password, access, lost-password
Calendarscalendars*
Computers and Devices

computers*
devices

Email

email*
bearmail, office365,
mac-mail, windows-mail, outlook, thunderbird

Learning Management System

LMS*
(see Learning Management System labels below)

Networking

networking*
wireless, vpn

Printers and Printing

print*
bearprint
Services

service*
microsoft-it-academy, bomgar, digital badges

Software

software*
microsoft, mac, dell, android, windows, osx, ios, apple, linux,
kindle, blackberry, nook, sas, spss, adobe, acrobat, dreamspark, kivuto

Student Academic Processesmy-missouri-state (usually)
Systemssystem*
my-missouri-state, banner, my-learning-connection, bdms, java,
inb, adobe-connect, digital-measures, inqsit, eportfolio, portal, luminus,
class-schedule-building, faculty-grade-entry, gwapp, dublicate-pidm,
projected-course-offerings, workflows, fee-waiver, degree-works, 25live,
web-press

Web Browsers

browsers*
safari, chrome, firefox, ie, edge

Other allowed labelsmobile, desktop, virus, storage-solutions, tech-tips, security,
greenwood, peer-to-peer, web-editing

* Labels marked with an asterisk should be included on all pages in that section.

Learning Management System labels

Page TopicsLabels
All LMS pagesLMS*
Blackboard pagesblackboard, blackboard-learn, collaborate,
User rolestudent, instructor
Landing page headings

basics, communication, assessment, jumpstart, content, student-performance,
endpoint, content-design,
grading, learningpath, lms-best-practices, scorm

Third-party tools

respondus, turning-technologies, clickers, ets, mediasite, softchalk,
my-math-lab, myedu, lockdown-browser, xplor, safe-assign

Status labels

Add a Status label if the page meets these conditions: 

  
Deprecated Page should be marked for deletion.
Developing Page is currently under construction
Review Someone should review the content.

 


For questions or comments, contact the Computer Services Help Desk
HelpDesk@MissouriState.edu
417-836-5891