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: https://kb.parkland.edu/internal.
3. Sign in with your ParklandOne username and password.
4. Select Admin Tools from the KB Help menu towards the upper right-hand section of the screen.
5. Select the Documents tab at the top and then click on the New Doc link towards the upper left-hand section of the screen.
6. Add an appropriate Title.
7. The Keywords are used when users are searching for articles within the KB. Any word that appears in the title will automatically be a keyword and therefore it is not necessary to use any of those words in this field.
8. 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.
9. You may wish to add a brief Summary describing your article. Note: If a summary is superfluous, please press the space bar on your keyboard within this field so that it registers as text since this is a required field.
10. Please add all of your content to the Body field and be mindful of the instructions linked to at the top of this article as well as the bullet points in the Additional Tips and Information section at the bottom of this article. As you are working, select the Save change button often to ensure that you don’t lose any work in the event of a power outage or something like that. The button is located right below the body of the article.
11. 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.
12. 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.
13. 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).
14. 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.
15. 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.
16. Relevance will typically be the default which is My group / sharing groups.
17. Once you have Previewed and Saved your document and are ready to submit it to Sara Stone in Campus Technologies for publishing, please select Request Activation and then Submit towards the bottom of the article. It will prompt you to confirm that you want to activate/publish your content and it will send her a request to review and publish it on your behalf. If you haven’t finished the article but are done for the day, keep the Status set to In Progress and select Submit. To return to your In-Progress document later, please do the following:
- Navigate to https://kb.parkland.edu/internal.
- Click on the KB Admin Tools link.
- Select the Documents tab.
- Select In Progress on the left-hand side.
- Select the Edit option in the table adjacent to the appropriate article.
- As you are working, select the “Save change” button often to ensure that you don’t lose any work in the event of a power outage or something like that. The button is located right below the body of the article.
- If you have finished editing the article and it is complete, select Request Activation and follow the instructions in step 17 above.
18. Additional Tips and Information:
- Website content, Word documents, PDF's, etc. do not play nicely with the KB editor when pasted directly into the body of the article. If you have existing documentation that you would like to insert into a KB article, first paste it into Notepad, WordPad, or TextEdit, which will erase the formatting. You can then copy from one of those programs and paste into your KB document. Next, use the KB editor tools to recreate your original formatting.
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.
The Snipping Tool (Windows), Grab Tool (Apple), and Print Screen options are invaluable for capturing images. Red borders and arrows can be added to highlight parts of the image if you open up the file in the MS Paint application, for example.
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.
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 creating a document but need to close your session, be sure to click Save change and then Submit and you can come back to your document later. It will be stored under the In Progress link within the Documents tab. 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.
Please contact Sara Stone email@example.com with questions or if you need any adjustments to be made, such as adding a header or creating a sharing group. If Sara or another Admin is unable to resolve the issue, they can contact KB tech support via email at firstname.lastname@example.org.