Introduction
This article details a set of standards for articles within our KB. These standards assist us in delivering a level of consistency with the content we provide to our customers and internal staff. As a part of these standards, we ask that you write and think in a 'user voice' as you design and write knowledge base articles.
General Stylizing
When writing articles, there are some general stylizing that we want to follow. While I recommend starting with an article template relevant to the article you are writing, this will help those that are starting from scratch or looking for additional info. Additionally, here is an Example Article you can check out.
Article Sections
Articles usually should follow a principle of a few main sections including Introduction, Body or Main Content (Examples: "Steps", "Guidance", etc), and Additional Information. These main sections should use the Heading 2 format for a title. Sub-sections within those should use Heading 3 and for each level down, proceed with the next level Heading. Consider indenting sub-sections that use Heading 4 or beyond.
Introduction
Usually a brief paragraph describing the article
Body or Main Content
This is your main content. You can use multiple sections if appropriate. Some examples would include "Steps", "Guidance", "Features"
Additional Information
Please include some information on what the reader can do for next steps or who to reach out to for questions/comments. This will also assist with giving the chatbot additional info for user questions. Ideas/Examples:
- Information on submitting a specific ticket > If you have issues, please submit a TeamDynamix - Report an Issue ticket and our team will get back to you.
- Another site or maybe a higher level category in the KB
- Contact the Help Desk. Example: If you have any questions, need additional assistance, or cannot find what you are looking for, feel free to contact our Technology Support Center.
Other Formatting Guidance
Here are some additional notes. Some of this guidance can be seen and described in the Example Article.
- I don't recommend copying content from Word or other sources that may include formatting. That typically brings over a lot of junk html formatting that causes issues on the article and will need to be removed. Your best bet is to start writing an article directly within TDX.
- Do not adjust text font or sizes beyond using the default Header options.
- When using hyperlinks, I'd recommend to set Target to New Window (_blank) so links default to opening in new tabs.
- Consider using HTML templates for alerts such as warnings, information, etc.
- When adding pictures to an article, you have two methods to do so.
- You can copy/paste an image which will give you a thumbnail version of that image in which readers can click on to enlarge. I normally would recommend this option.
- You can also paste images inline by using the article editor ribbon and clicking the "Image" button. This will be the full image that you can resize on the page.
- When adding images within a bullet or numbered list, you may encounter some formatting issues. If you need help, don't hesitate to reach out.
Article Templates
The following is a listing of different types of articles that you might choose to write. While most of these describe a specialized template, feel free to follow the General Information standards if your content does not fit the other content types.
Article Content Type Standards:
How-to Standards
| Subject |
How to [what ever you are trying to do] |
| Body |
- Select the drop-down for templates in the content editor.
- Select the How to KB Article Template.
- Complete the body by using the template as a guide.
- Add HTML Components as needed.
- Delete elements from the template that are not needed.
|
| Tags |
How-To, Audience (Students, Faculty, Staff), Service, Application |
| Summary |
This article describes how to [whatever you are trying to do] in the [whatever service or application]. The target audience is at least one if not all of the following [students, faculty, staff, guest as applicable] or [targeted group]
|
| Example |
How to Change a Ticket |
Go back to article standards
Quick Start Guide Standards
| Subject |
[Whatever the article is about] Quick Start Guide |
| Body |
- Select the drop-down for templates in the content editor.
- Select the Quick Start Template.
- Complete the body by using the template as a guide.
- Add HTML Components as needed.
- Delete elements from the template that are not needed.
|
| Tags |
Getting-Started, Audience (Students, Faculty, Staff), Service, Application |
| Summary |
This article will guide you through a brief set of steps to get started with [whatever the article is about]. The target audience is [students, faculty, staff, guest as applicable] or [targeted group] |
| Example |
Skype for Business Quick Start Guide |
Go back to article standards
FAQ Standards
| Subject |
[Service or Application] FAQ |
| Body |
- Select the drop-down for templates in the content editor.
- Select the FAQ Template.
- Complete the body by using the template as a guide.
- Add HTML Components as needed.
- Delete elements from the template that are not needed.
|
| Tags |
Frequently-Asked-Questions, Audience (Students, Faculty, Staff), Service, Application |
| Summary |
This article describes frequently asked questions about [whatever the article is about]. The target audience is [students, faculty, staff, guest, as applicable] or [targeted group].
|
| Example |
OneDrive FAQ |
Go back to article standards
General Information Standards
| Subject |
[Name of the service/application] Information |
| Body |
- Select the drop-down for templates in the content editor.
- Select the General KB Article Template.
- Complete the body by using the template as a guide.
- Add HTML Components as needed.
- Delete elements from the template that are not needed.
|
| Tags |
General-Information, Audience (Students, Faculty, Staff), Service, Application |
| Summary |
This article will provide general information about [whatever the article is about,] The target audience is [students, faculty, staff, guest as applicable] or [targeted group]
|
| Example |
Unified Communications Audio/Video Device Information |
Go back to article standards
Issue/Resolution Standards
| Subject |
[Statement of the Issue (target audience perspective)] |
| Body |
- Issue- Heading 2
- Service/ Environment/ Application- Heading 2
- Cause(optional)- Heading 2
- Resolution- Heading 2
- Additional Resources- Heading 2
|
| Tags |
Issue-Resolution, Audience (Students, Faculty, Staff), Service, Application |
| Summary |
This article will provide a resolution to the issue, [statement of issue from the target audience perspective]
|
| Example |
TeamDynamix - You Do Not Have Permission To Access This Application |
Go back to article standards
Standards for Knowledge Base Standards Article
| Subject |
[Name of the application/service] Standard(s) |
| Body |
- Purpose– Heading 2
- Application- Heading 2
- Briefly describe who must follow this standard (e.g. students, faculty, staff, etc.) or targeted group (e.g. graduate students, adjunct faculty, etc.)- normal heading
- Briefly describe any conditions under which this standard must be followed (e.g. "when storing data that is highly sensitive," "when using a personal device," etc.)- normal heading
- Exceptions- Heading 2
- Briefly describe when an exception may be granted and how to request an exception- normal heading
- Standards- Heading 2
- Briefly list or describe the standards. An additional table or area for content may be added below for standards that require more than a brief explanation.
|
| Tags |
Standards, Audience (Students, Faculty, Staff), Service, Application |
| Summary |
This article will provide the standards for [whatever the article is about]. The target audience is [students, faculty, staff, guest as applicable] or [targeted group]
|
| Example |
ISU Computer Standards |
Go back to article standards
Resource Links
| Subject |
[Product Name] Resource Links |
| Body |
- Introduction- Heading 2
- Enter a brief description of the product and who uses the product.- Normal format
- Resources- Heading 2
- Enter a hyperlink describing the resource it is linking to. These are normally resources provided by the vendor or another group outside of of ISUs knowledge base.
- User's Guide
- Training Video
- [Specific subject] Tutorial
- Additional Resources
- Provide information on where to find further support, i.e. help desk or other ISU support resource.
|
| Tags |
Resource-Links, Audience (Students, Faculty, Staff), Service, Application |
| Summary |
This article provides links to resources for [product name]. The Target Audience is [student, faculty, staff, guest as applicable] or [targeted group] |
| Example |
OneDrive Resource Links |
Go back to article standards
These standards have not been defined
| Subject |
[Application/ Service] Support Resources |
| Body |
1. Table for ISU support resources
2. Table for Vendor support resources
|
| Tags |
Product-Support |
| Summary |
This article provides product support resources for [name of the product/application]. The target audience is [students, faculty, staff, guest as applicable] or [targeted group]
|
| Example |
|
Go back to article standards
These standards have not been defined
| Subject |
[Service] Overview |
| Body |
Priority – how critical is this service
Service partners (others who are experienced with this service and help to administer/support the service)
Service posture (we fully support/somewhat support/minimally support . . . with something about what that means for this service)
Training posture (we can provide in-depth training/some training/no training at all)
How we evaluate the success of this service
Other service elements
Service history (major inflection points in the delivery of this service)
|
| Tags |
|
| Summary |
|
| Example |
Kronos Support Resources |
Additional Information
If you have questions, please reach out to Chris Middleton.