Create a New Article Request
Table of Contents
Scope
Intended Audience: All OIT & MMN Employees
This article outlines how to create a knowledgebase article request according to OIT standards. All article requests should match the standards outlined here before being submitted to the Solutions Hub for fabrication. Multiple articles will be merged to craft a one-stop article to suit any user or permission level.
This article is for subject-matter experts to outline a knowledgebase article to articulate to our team or our clients the processes that onboard, train, or communicate instructions cohesively.
Requirements
• Write the needed doc as a subject-matter expert.
• Submit either a Word Doc or Scribe to Docs@oit.co
• The Solutions Hub will schedule time to review and confirm screenshot accuracy if necessary.
Troubleshooting
If you encounter any issues during the execution of [article name], refer to the following troubleshooting tasks.
This should be formatted in a numbered list.
- Seek vendor support.
- Common Issues.
- Solutions/Things to look for.
- Things to consider prior to pursuing.
Best Practices:
Finally, add best practices if applicable.
Troubleshooting
As we craft docs, I'd like us to draw from past client experience to address common hurdles and highlight best practices.
We currently have 1,437 articles published in Helpjuice. The goal is to condense these docs down to less than 100 articles.
These articles will be client-facing, with private Accordions available only to OIT & MMN staff.
Doc Consolidation
We currently have 1,437 articles published in Helpjuice. The goal is to condense these docs down to less than 100 articles.
This is a gigantic task. As requests are received, if there are docs that can be merged please denote them.
- Example:
- Docs 2 Merge: <followed by hyperlink><hyperlink><hyperlink>
- When proceeding, analysis of the Parent/Sibling doc relationship will be relevant.
- If unsure:
- Drop a message on the Solutions Hub Teams Channel.
- Help will be provided.
- Drop a message on the Solutions Hub Teams Channel.
- If unsure:
This is a long-term goal. Not every doc will/ needs to have the Doc Consolidation addressed. But if you know of supporting docs to add, please add them to the KB request.
____________________________________________________________________________________________
New Doc
EXAMPLE:
Title
Ensure that the title is a clear description of the objective of the article. Note the platform used in the title. Use present tense when writing the article and avoid phrases like “How To”.
Bad Title Examples
Agent Portal, Making a New Partner, How to Add a Phone Number, Provision Phone
Good Title Examples
Rev.io: Create a Channel Partner Agent, NDP: Create a Reseller User, Bandwidth: Purchase a DID, Manually Provision Yealink Devices.
Provide Folder & Permission Info
- Please tell me what folder the article should live in.
- Please tell me what the permission level should be.
- The options are:
- Public
- Internal
- Private
- The options are:
Scope, Requirements, Critical Data, & Troubleshooting
Scope
A Scope section should be included at the top of the article with a short sentence or two as to what will be accomplished by this article, along with the intended audience.
Intended Audience: An intended audience should be listed on all articles. Intended Audience must be chosen from the following list: All Employees, Tier 1/2/3 Technicians (or higher), White Label Partners, Channel Partners, All Users, <Department Name> Department
Then provide a brief synopsis of the information to be covered and when to be implemented.
“The goal is to craft a document for both internal and client use. If you are ready to craft and submit a knowledgebase article to the Solutions Hub, proceed.”
Requirements
The requirements section should list any needed logins (including permissions) or additional articles that may be needed for reference.
This should be formatted in a bulleted list.
Troubleshooting
If you encounter any issues during the execution of [article name], refer to the following troubleshooting tasks.
This should be formatted in a numbered list.
1) Common Issues.
a. Solutions/Things to look for.
2) Things to consider prior to pursuing.
Best Practices:
Add any additional tips or best practices.
Formatting
- Don't worry about the format, just place text in logical order.
Submit for Creation
Please denote NEW in the email request title. Verify that all information is orderly and accurate and that the article is uniform according to the steps outlined in this article.
Once you have verified your article is ready, email it to Docs@oit.co for Review.
Scribehow Process
-
When sharing the Scribe:
-
Under OIT, Select Can Edit.
-
Under OIT, Select Can Edit.
- Failure to do so will prohibit Solutions Hub staff from saving or editing screenshots.
Finish
The Solutions Hub will denote the KB originator at the base of each article.
Edit Doc
When Submitting an Edit for an Existing Doc:
- Please denote edit in the title of the email.
- Link the published doc you want to be edited.
- You can embed the hyperlink in the article title OR paste it out long format.
- Denote what section/# and corresponding title you want to change the contents of.
- Example:
- Change step 9 to - Send the employee an email using the Employee of the Month template in ClickUp.
- Example:
- If adding a section/#, please denote between which 2 headers the new section belongs.
- Example:
- We need to add a section in this doc https://help.oit.co/sip-trunking/bring-your-own-telco-byot-considerations to cover sip signalling ports that are supported.
The section to be added is called "SIP Signalling" and should be directly below the Voice Traffic section and before the SMS/MMS section.
SIP Signalling
---------------
Carrier connections should use port 5060 for UDP and TCP traffic and port 5061 for TLS traffic. We do not support BYOT connections that use SIP signaling on any other ports.
If the BYOT carrier can not accommodate this, then utilizing an SBC such as our preferred SBC of FreeSBC https://www.telcobridges.com/<https://www.telcobridges.com/,> (but any can be used) to handle the conversion of the carriers port to our servers.
- We need to add a section in this doc https://help.oit.co/sip-trunking/bring-your-own-telco-byot-considerations to cover sip signalling ports that are supported.
- Example:
- If Troubleshooting or Best Practices can be added to the doc, please denote and Solutions Hub will craft the Troubleshooting area and populate the needed data.