Company Documentation Template and Style Guide

ITBoost Documentation Template and Style Guide

Summary

Please use this guide along with the [Redacted] Knowledge Base Style Guide [Hyperlink Removed] to create effective knowledge base articles.

Details the document's purpose and may have some information on why the issue may be happening.

Documents should ideally only have about three or four lines in this section.

Table of Contents

A Table of Contents section may not be necessary for all documents, like informational documents that are a quick list or table.

There is currently no method from the vendor to anchor linking headers, but staff members can use the CTRL-F function to find headers quickly.

A) Important Details/FAQ

B) Step of a How-To Document/ Heading for Long Informational Document

C) Possible Error Heading

D) Additional Style Recommendations

A) Important Details/FAQ

• This section should have necessary prerequisites and answer questions commonly asked by service desk staff.

• The section may not be necessary for all documents, especially short or strictly informational documents.

• This feature could be helpful in extremely long documents or clients with several exceptions/special conditions/frequent detail changes.

• Function titles, group names, commands, scripts, and keywords can be highlighted here in bold or another text color.

• The FAQ does not have to be strictly uniform across documents, as different questions will apply to different situations.
  

Examples of important details that can be in this section:

• [Redacted]: How all creation/reactivation/disable requests must come through Cherwell.

• [Redacted]: Reminder that all users must be authenticated before account modification.

• [Redacted]: Reminder that we do not have enterprise access, so we cannot search for accounts across facilities.

• [Redacted]: Reminder that switching to their VPN may drop the call and inform the user of this possibility.

• Related documents may also be linked here.

Examples of FAQ questions that can be included in this section:

• Who Can Request Modification

• How to Relay Credentials

• Expiration Date

• Credential Format

• Team to Escalate To/Contact for Assistance

• Critical/Non-Critical Escalation

B) Step of a How-To Document/Heading for Long Informational Document

• Any pre-requisite information for this specific step should be stated in one or two sentences above the actual steps.

• Steps should then be numbered, with function titles/group names/commands/scripts highlighted in bold or another text color.

• A document that displays this format well is the PointClickCare: New User Creation Procedure [Hyperlink Removed] document for [Redacted], specifically the Create User Account in PointClickCare and Verify User Account sections.

• Every major step should have its own heading and be listed in the Table of Contents.

• For example, in the [Redacted] document just mentioned, Create User Account in PointClickCare and Verify User Account have their own headings and should be listed in the Table of Contents.

• Long tables, charts, grids, and lists should be laid out in separate documents linked in the steps.

• A great example of this is the PointClickCare - New User Creation Procedure [Hyperlink Removed] for [Redacted], which lists additional security roles as a separate appendix/informational document.

C) Possible Error Heading

• These sections should include possible roadblocks and common error messages encountered by users and the service desk.

• Photos of the error messages should be included so the service desk can follow along with the user.

• If the process to correct the error is not client-specific and can be searched for online, we can link an article from Google or provide some keywords for service desk staff to search for on their own.

• If the process to resolve the issue is client-specific or has a specific document associated with the roadblock, we can link associated ITBoost docs here.

• The section may also include information on who to contact if the service desk cannot resolve the problem.

D) Additional Style Recommendations

Breaking Up Text

• Stray away from large paragraphs or blocks of text.

• The service desk typically moves at a fast pace, and we are looking for answers/information quickly, so the documents should be designed to be effective but simple.

• Adding line breaks to a paragraph increases our ability to find the information we need and process it quickly.

Hyperlinks

• All websites, external documents, email addresses, general links, and configurations should be hyperlinked within the document.

Images

• Unless the image has lines of text that must be visible, most images can be set at 25% image size.

• Larger documents bulk up the knowledge base documents, and we find ourselves scrolling quite a bit to get back to the text.
  

Sample Image Size

Prefixes: Important and Note Tags

• It is unnecessary to use the Note prefix to pre-requisite information, it is apparent that they are informational notes when placed above/before a set of instructions.

• Adding the !!IMPORTANT!! tag multiple times in paragraphs may cause clutter and lead the service desk to overlook the information, so please refrain from using this method.

• Please highlight crucial information in another text color, and refrain from highlighting entire paragraphs if possible.