HOWTO: Creating a KB doc from a template in the SCS KB
- Introduction
- Accessing the Knowledgebase Admin Tools
- Create a new document and select a template:
- Editing the document
- Publishing a document
- Additional Help
Introduction
This is a VERY SIMPLE guide to creating KB documents from a template. You can find more in-depth help in the KB User's guide.
- KB User Guide - Creating a document: https://kbadmin.apps.uillinois.edu/kbGuide/5235
- General KB Training: https://kbadmin.apps.uillinois.edu/kbGuide/search.php?cat=1867
Templates are a simple way to start a new document with many of the options below pre-selected for you such as topics, viewing restrictions, etc..
If you plan to make several KB documents and do not see an appropriate template, let us know at scs-help@illinois.edu and we can create a template for you.
Accessing the Knowledgebase Admin Tools
If you don't have access to the Knowledgebase Admin Tools,send an email to SCS Computing (scs-help@illinois.edu) requesting access. You can access KB Admin Tools using this link: https://kbadmin.apps.uillinois.edu/kbAdmin. You can also go to the SCS Internal KB (https://answers.uillinois.edu/scs/internal), log in, and then click on the KB Admin Tools link.
When writing KB documents, try to be as clear and concise as possible. Although screenshots are sometimes included, people should be able to understand what to do based on the writing itself.
IMPORTANT: If you have questions about a field (such as "Keywords" or "Site Access"), you can click on the field name in blue to get more information from the KB User's Guide.
Create a new document and select a template:
- Go to the KB Admin Tools (https://kbadmin.apps.uillinois.edu/kbAdmin), and click on Documents in the top header bar
- Click on Create a Doc in the left navigation
- Select the template you wish to use. Many options will be pre-set, depending on which template you chose.
Above the editor:
- Change the title
- Remove the word "TEMPLATE" and add a meaningful title
- If the document is for internal use, leave the word "INTERNAL" prepended to the subject
- For CORES labs, be sure to use the Lab name or acronym in the title, preferably at the beginning (NMR, Mass Spec, etc)
- If the document will be used on the SCS website, add
(web)
to the title- Example: NMR - Student training (web)
- Example: NMR - Student training (web)
- Remove the word "TEMPLATE" and add a meaningful title
- Add keywords - use as many as you can think of that someone might use to try to find this document
- NOTE: You do not need to repeat words in the title
- NOTE: You do not need to repeat words in the title
- Add a summary - this will appear on the KB article, right below the title
Below the editor:
- Topics:
- Check the topics to be sure that the correct topics are selected, and select any additional topics that seem relevant
- Topics are used to fill out the "Topic Tree" on the KB's homepage (https://answers.uillinois.edu/scs and https://answers.uillinois.edu/scs/internal) which can make documents easier to find
- Many topics will have sub-topics, so be sure to expand the top level and select the appropriate sub-topics
- If you do not see a topic that is appropriate for your document, email SCS Computing (scs-computing@illinois.edu) and request that a new topic be created.
- Write Access:
- The default option for write access is "Owner". Do not change this.
- Each template also has some default groups already selected - Change these carefully!
- You can see the members of a group by hovering your mouse over the group name. See the green circle below for an example.
- If other people should also have access to edit a document:
- Click on the [ ] next to Show other write access (see red arrow)
- Select the appropriate group(s)
- If the correct group doesn't exist, email scs-computing@illinois.edu and we'll add it
- If the document will be used on the Web, be sure to select the group "SCS Webmasters"
- Read access:
- For publicly available documents, no "read access" groups will be selected
For private/internal documents, some default groups will already selected. Add other groups that should have read access to the document- Click on the [ ] Show all read access next to "Read access" (or Show other read access if some read access groups are already selected)
- You can see who is in a group by hovering your mouse over the group name - see the green circle above for an example
- For publicly available documents, no "read access" groups will be selected
- Site access:
- Publicly available documents should have both "UillinoisSCS-External" and "UillinoisSCS-internal" selected. This allows a document to be read publicly without any authentication while also making it available to the internal KB site.
- Internal only documents should ONLY have "UillinoisSCS-internal" selected
- Owner:
- The document owner will be notified when the document's expiration is approaching.
- You will be the default owner of a new document. If that's OK, nothing more is needed.
- If you need to change the owner:
- Click [ ] Show Additional Fields (this is directly above the blue "Submit" button at the bottom of the page)
- Change the owner to whoever should be responsible for the document.
Editing the document
- Save the document.
- Click blue Submit button. This will save the document, and the status will be "In Progress".
- NOTE: The first time you save a new document, the default status is "In Progress" and the "Active" status is unavailable. To make a document available to the KB (and website if applicable), you'll need to edit the document and then you can change the status to "Active". See Step 2 below.
- NOTE: The first time you save a new document, the default status is "In Progress" and the "Active" status is unavailable. To make a document available to the KB (and website if applicable), you'll need to edit the document and then you can change the status to "Active". See Step 2 below.
- Click blue Submit button. This will save the document, and the status will be "In Progress".
- Click Edit document
- See https://answers.uillinois.edu/scs/107048 for additional help with editing a document
- See https://answers.uillinois.edu/scs/107048 for additional help with editing a document
- Add your content to the "Body" section. Links are below to KB help guides:
- Using the TinyMCE Editor: https://kbadmin.apps.uillinois.edu/kbGuide/114570
- NOTE: You can paste Microsoft Office and Google Docs content directly into the KB editor (TinyMCE). When you paste, you will be asked if you would like to keep or remove formatting. Please choose Remove formatting. Please note that this only applies to extra formatting and styling; basic formatting, such as bolded text, will always be retained.
- See the KB FAQ at: https://kbadmin.apps.uillinois.edu/kbGuide/page.php?id=5233#FAQ
- Using the TinyMCE Editor: https://kbadmin.apps.uillinois.edu/kbGuide/114570
Screenshots / Pictures
"A picture is worth a thousand words" - trite, but still true. A quality picture can make all the difference in helping people understand what you're trying to say.
- Screenshots can be taken using whatever function your laptop uses.
- Windows: [Win Key] [Shift] [S]
- Mac: [Command] [Shift] [4])
- Use whatever editing program you find intuitive. It doesn't need to be fancy.
- Use boxes and arrows to point out where the reader's attention should be drawn
- Name the files well so you can easily identify where the picture is supposed to be used
- You'll most likely have to resize the image depending on what looks good and is readable. You can either adjust it in your editing program or within the HTML of the document.
Uploading Images
For an image to be used in a KB document, it must be uploaded to the KB server first. How this works is a little confusing.
- For most new documents, you'll want to click on the checkbox next to Create a new doc attachment folder - this is an attachment folder specific to this document.
- NOTE: You'll also see a link for "Open shared attachment folder" - as a general rule, do not use this. The shared attachment folder should only be used for items (attachments, images or screenshots) that will be used by multiple KB documents (this is not common).
- Once the document attachment folder is created, upload your photos onto the document by selecting Upload attachments or Open shared attachment folder which you can find a little under the Body text box.
-
- DO NOT move or delete images from the "shared attachment folder", as this will also remove them from any other document where that image is used.
-
Placing an image
- To add an uploaded image to a KB document,
Publishing a document
- Submit the document
- The default status when editing a document is "In Progress"
- Documents can have dual-status, such as "Active / In Progress" - this means that there is a version of the document that is available on the KB, and a version that is currently being edited.
- When you're ready for the document to be live, change the status to "Active" and click on the blue Submit button.
- The "Accessibility Checker" will appear if there are any accessibility issues. Please review the issues to determine if changes are needed.
- This can be triggered by:
- Tables that do not have a caption
- Non-black text
- Images that do not have alternate (descriptive) text
- See https://kbadmin.apps.uillinois.edu/kbGuide/116740 for more guidance on the Accessibility checker
- This can be triggered by:
- Once the document has been successfully set to "Active" and the "Submit" button selected, you'll see the following screen.
- Note that the progress bar shows that it's active.
- To extend the expiration, click on the Extend expiration button (see the red arrow, below).
- The default status when editing a document is "In Progress"
IMPORTANT NOTES:
- If you do not change the status to Active after making changes:
- If the document was previously made Active, then the "Active" version (the version shown on the KB) will be the old version and your changes will be kept in an "In Progress" state. If that happens, you'll see that the document has a status of "Active / In Progress"
- If the document was saved after creating it in the "In Progress" state, then no document is available on the KB.
Additional Help
If you need additional help, have questions, or want to make advanced edits, contact SCS Computing staff at scs-help@illinois.edu.