Parkland College KnowledgeBase - Best Practices for Writing Documents
Best practices and guidelines to follow while authoring Parkland College KnowledgeBase articles.
1. Please reference the following articles for instructions and best practices to follow while authoring. This will ensure that all of our documents are as consistent as possible.
- KB Author Training - Creating a New Document
- KB User's Guide - Documents Tab - Document Style Guidelines
- KB User's Guide - Documents Tab - Image Guidelines
- KB Author Training - Title, Keywords, and Summary Fields
- KB Author Training - Body Field - Editor Options: Design (WYSIWYG) or HTML mode
- KB Author Training - Body Field - Design (WYSIWYG) Editor Controls
- KB Author Training - Body Field - HTML Editor Quick Code Buttons
- KB Author Training - Attachments and Revisions
- KB Author Training - Editing an Existing Document
2. Enter the following url into your web browser (Internet Explorer is not recommended for creating documents that include images or hyperlinks): https://kb.parkland.edu/internal.
3. Your username is your full Parkland email address and your password is your ParklandOne password.
4. Select Admin Tools from the KB Help menu towards the upper right-hand section of the screen.
5. Select the Documents tab and then click on the New Doc link towards the upper left-hand section of the screen.
6. In the "Page footer" field, please select Tech Service Desk Footer from the drop down options, if appropriate. This will add a footer with the location, contact information and hours of the Tech Service Desk.
7. We are using a limited number of "Topics" at this time. If your document is related to Business Intelligence, BYOD, Cobra, Office 365, Parkland IT Standards, Parkland Library, ParklandOne, or Wi-Fi, you can check the appropriate box.
8. We have three "Audience" selections in place - Faculty, Staff, and Students. Select one or more, depending on who is the target audience. Users can then select their group on the homepage to tailor their search to documents that are specific to them. Please note: Student related articles should have all three audiences checked as employees are often the ones that help them with issues.
9. "Write Access" will typically be the default which is "Owner group (+ owner)". This simply means that any of the Parkland College KB authors have write access to the document. If you don't want that, please select Owner Group Admins (+ owner).
8. For "Site Access" you will typically select both options, Parkland-internal and Parkland-external. This means that the article will be viewable by both authenticated Parkland users as well as the general public. If there is a need to restrict access to Parkland users, select Parkland-internal only.
10. "Campus Access" will typically be the default which is Defer to Site Access. Ext/Internal with campus login should be selected if "Site Access" is restricted to Parkland-internal.
11. "Relevance" will typically be the default which is My group / sharing groups.
12. Once you have previewed and saved your document and are ready to submit it to Sara Stone for publishing, please select Request Activation. This will cause the document to appear in her queue to review and publish.
13. Additional Tips and Information:
- Word documents do not play nicely with the KB editor. If you have an existing Word document that you would like to translate into a KB article, first paste it into Notepad, WordPad, or TextEdit, which will erase the Word code. You can then copy from one of those programs and paste into your KB document. It may still require further editing.
- Copying and pasting content and images directly from other sources such as websites is not recommended. Sometimes there are no issues but other times the formatting changes and images appear broken when you publish the article. It is always best to paste text into notepad first and then copy and paste into your article. Images should be saved and uploaded into the document's attachment folder rather than being pasted in.
- If you feel like the addition of a Summary is redundant to the title, just put a space in that field as a placeholder since it is a required field. It accepts it as text.
- The Snipping Tool (Windows), Grab Tool (Apple), and Print Screen options are invaluable for capturing images. Red borders can be added to highlight parts of the image if you open up the file in Paint.
- In order to add images or files, you have to first save them to the document's attachment folder. Your document must be saved before the attachment folder becomes a viable option. Click on the link just under the Body that says, "Open doc attachment folder." You can then browse and upload images and files. Place the cursor where you would like to insert the attachment. For images, select the "Quick" link next to the image in your folder and it will insert it once you have given it a name. If you are inserting a link to a file, click on "Plain" if you don't want it to open in a new window and "NewWin" if you do. Important Note: Images do not upload well if you are using Firefox. Internet Explorer works best.
- The "Link doc" and "Include doc" icons in the KB editor are great for referencing existing documents within your article. Simply type in the document number where you would like to place the link or embed the article and then highlight it. Once the number is highlighted, click the appropriate button to link or embed.
- The "Horizontal rule" icon in the KB editor is great for separating different ideas or instructions within your document. For example, if the topic is Wi-Fi setup and you are including instructions for both iOS and Android devices, it might be a good idea to separate the instructions with a horizontal rule. It is also pleasing to the eye to use the horizontal rule if your document is loaded with tons of instructions and images. The line delineates each step in the process in an organized fashion.
- Documents are automatically set to expire four years after the creation date. The document owner will receive "review" email prompts every six months so that they can go in and edit and/or update information. They also have the ability to change or reset the expiration date as it is about to expire. If the document is not reviewed by the expiration date, it will no longer be seen on the live site but can be updated and renewed after the fact.
- If you are not done with a document, but need to close your session, simply click Save change and you can come back to your document later. It will be stored under the In Progress link within Documents. If a document has already been published, but you need to make a change to it, it can be found within the Active link. Simply search for the KB number and then select Edit next to the title. You will need to add a comment to the bottom field of the article and click Submit. It will then bring up a screen where you will need to select Edit once again. Be sure to save your changes. The document will remain "In Progress" until you select "Active" or "Request Activation" at the bottom of the screen.
- If you are wanting to send a link to a document that you created, please be sure to send the link from the external site at kb.parkland.edu.