On this page:
- Daily review of articles created/changed
- Comment moderation and review
- Anonymous feedback button submission review
- Respond to email@example.com
- Authoring permission requests
- Author support
- Maintain Top 5
- Category tree maintenance
- KB cleanup process
- Maintain the KB Handbook and Best Practices
- Macro creation and maintenance
- Student KB Editor hiring/training/oversight
- KB training
- Google Analytics
- Fixing Archived IS&T Website Links
Do a Style Review on all articles edited or changed in the KB the previous day (or weekend). They're easily found by subscribing to the daily digests of changes in the KB (see: Watching Articles for instructions).
If any issues are discovered in the style review, your options are:
- Contact the author - best for major content-related issues or to address repeat Best Practice discrepancies.
- Edit the article - best for time-critcal issues, high priority content, complicated fixes, or minor content issues you know how to fix.
- Put the r-style tag on the article so a student KB editor will fix them. - best for ugly articles, wiki markup issues, accessibility fixes and lower priority articles.
Comments show up in Daily Digests along with all other changes and creations in the KB. Comments should be reviewed and the following actions taken. A few common scenarios:
- Spam or inappropriate content - Remove it.
- Feedback or suggestions for improvement to articles - Treat it the same as the feedback button submissions. Once the appropriate action has been determined, remove the comment.
- Additional information - Review it. If it is correct, determine if you think it should remain a comment or be merged into the article itself. This is a judgment call. If you do merge the content into the article, remove the comment.
- Requests for help - create a ticket for them with the help desk and remove the comment.
The feedback buttons at the bottom of the articles that say "Inaccurate" or "Obsolete" cause email to be sent to the hermes mailing list and an RT ticket to be created. This feedback needs to be reviewed by a Knowledge Manager to determine the correct course of action. Each one can be its own little research project.
Note that feedback is not always correct. Users seeking troubleshooting documentation are often confused and sometimes experiencing strange exception case behaviors. Many are not MIT community members and their system configurations for systems like Exchange are different than ours. Feedback must be validated to be sure it is correct and relevant to our environment.
Common kinds of feedback and actions are as follows:
- Spam - Delete the ticket.
- Help request - If it has contact information, move it to the appropriate help desk queue. Otherwise feel sorry for the anonymous user and resolve the ticket.
- Request for archival - Many of our content area experts know they can request to have content archived via the feedback button systems. Usually these are signed and can be acted on as requested. If they're not signed by a content area expert, determine if archival is appropriate or not before archiving.
- Broken link report - Verify that the link is broken. Often certificate issues are reported as broken links. If it is broken, attempt to fix it by finding the correct link and replacing it. If you can't find a replacement link, contact somebody about it. Your options are usually a recent author, a content area expert, or a service owner.
- Complaint about a product/service - If constructive, pass along to service owner. If not, simply resolve the ticket.
- "It doesn't work" - Check the IP address to see if they are on campus. Frequently non-MIT (or off campus) people use our knowledge. Many of our services require certificates or use of the VPN off campus to work. This is frequently the reason for such feedback. Then review the article content. Test it if you can. If you can confirm the content is valid, close the ticket. If you can't, reach out to content area experts or service owners for further review.
- Suggested documentation fix - Review the documentation and test the fix. This may require reaching out to content area experts or service owners depending on the product/service and your level of access/expertise with it.
- Duplicate article - Find the duplicate. Merge the two articles into one. Replace the extra article with a redirect to the merged article.
This is the main contact list for the KB that feeds into an RT queue. Generally the requests made fall under something in another section here. Follow the appropriate instructions for whatever kind of request it is. If it's Spam delete it. If it's a help request, move it to the appropriate Help Desk queue.
Any MIT community members are able to become KB authors and gain authoring permissions in the Community Contributions space. SIPB members and prospectives are granted it automatically. IS&T staff should automatically have authoring permissions for the IS&T Contributions, Community Contributions, IS&T Internal and Draft spaces. Additional permissions are granted on a case by case basis. If you're not sure if a user should be granted the requested permissions, check with firstname.lastname@example.org.
- Before attempting to grant permissions, check to see what permissions the user already has. Navigate the blue authoring menus Edit > Administration > Site Administration That will take you to the "Administration Console". Select "Manage Users" and search for the user. You'll be able to see all their group memberships there.
- How do I give someone authoring permissions in The Knowledge Base? The short answer is to add them to the appropriate Moira list and send them a Permissions reply email for MIT affiliates. You may need to edit it slightly to address what specific access they have been granted.
(that article needs editing for more spaces, a link to the spaces/permissions page and some serious cleanup)
- Note: Moira can take a couple hours to update permissions. If a user needs them granted immediately, grant the permissions via the Moira group and via the KB. Click on "Edit Groups" when you're viewing the user's permissions. Note that changes MUST be made in Moira as well as in the KB directly because the Moira permissions take precedence and will wipe out any conflicting changes made directly in the KB at the next refresh.
- Find out what groups and Moira lists correspond to what permissions at Groups, spaces, Moira lists and permissions in the KB
Sometimes authors contact the KB team for assistance authoring articles. Some fairly common requests:
- Broken wiki markup that needs fixing.
- Content they don't know how to structure.
- An "ugly" article they want to make look nice.
- Wordsmithing assistance.
- I need a macro.
- How do I make my article look how I want it to?
- How do I get my word document or other thing outside the KB into the KB?
Generally you work with the author to help them with their issue. If it's not time critical, student employees can be very helpful in converting things like word documents into KB articles. If it's a large amount of content outside the KB, a migration project may be in order instead. That's something to escalate to KM Core or KB Tech Core depending on if it's a purely technical issue or has more organizational implications.
Note: Many broken wiki markup issues are related to having copied and pasted from the web directly into the KB authoring environment. This can bring along hidden text that is impossible to remove. Copy the article into a text editor to avoid losing any data, revert the article to an earlier, non-broken version of the article, then edit from there to include the content saved earlier.
The Top 5 KB articles are shown on the KB Home page and the IS&T Website home page. They are controlled by adding the ist-top-five label to articles. If more than five articles have the label sit-top-five than the five most recently edited articles will be displayed.
Due to vagaries of the setup of the RSS feed, any articles older than 6 months will not show up on places outside the KB (like the IS&T website) that display the top five. Check regularly to make sure KB articles in the top 5 have been updated within the last 6 months. Inconsequential edits can take care of this easily.
The Category space contains a structured tree that organizes content by topic. The tree structure is based off the Service Catalog on the IS&T website. Many additional topic areas are covered in the KB that are not in the service catalog, so it is not an exact match. This category tree allows project teams, users and maintainers to easily identify content related to specific topics when efforts around cleanup, renewal, releases and sunsets occur. Some users and consultants also prefer to browse versus searching when looking for generalized information or searching is difficult due to commonality of terms.
The Category tree is in its own space and is simply a tree structure based on parent/child relationships. You can change a category's location on the "edit" screen by editing the "Location".
Category pages generally only contain:
- A title, which is what appears in the category tree
- The category macro, category:label
Category labels are typically in the formats:
- c-label - a standard category label that indicates the category and something descriptive for the topic. Examples are c-exchange, c-firefox, c-security.
- olc-label - categories originally imported from the OLC Stock answers and are usually related to Athena. They work just the same as the standard category labels.
Creating new categories is easy. Simply copy an existing one and edit the content and location. When creating a new category label, keep it as simple as possible so it's easy to add and make sure it's not already in use. If it is already in use, you should notice immediately when your new category is already populated with a bunch of articles that already had that label. Just try again.
- How can I find a category without digging through the category tree?
- What are categories and how do I add an article to a category?
An annual process has been created to label articles that have not been edited in over two years (except by student editors for style/accessibility). This is done by KB Tech Core These articles are then reviewed by KB maintainers, content area experts and other volunteers for currency. This is a key part of the KB Knowledge Life Cycle that promotes updating or archiving outdated content instead of letting it linger causing confusion and cluttering search results.
Keep the KB documentation on using the KB up to date. When authors ask questions that aren't already documented, consider adding an article to document that procedure. Also, update the Best Practices with guidelines to address any new issues that arise.
Be very careful when creating and editing macros. Many of the macros in the KB are necessary for the theming. Breaking them can make the KB anywhere from ugly to almost impossible to use. Be very careful. Test on staging before you make any macro changes on production.
For day to day purposes, generally authors request content macros. They're often support notices or warnings of some kind that need to appear on many pages. Being able to create once and centrally update them as support status changes or bugs are fixed saves a lot of effort.
- To create/manage macros go to Administration Console > User Macros
- The easiest way is to find a similar one that already exists and copy the settings.
- Test on dolios. Dolios.mit.edu is the staging version of the KB. You can test things there and not worry about breaking the KB.
- Keep a copy in AFS repository
[Student employees] primarily do style reviews on articles nominated for it by authors, maintainers and customers. They also take on other projects as skills and needs allow. At various points they have assisted with content migrations, cleanup efforts, importing content, labeling, and standards implementation.
Student employees have been hired alongside help desk consultants as part of that process, and trained by KB Knowledge Managers to implement style reviews and in the use of tools necessary to do so. KB Knowledge managers also handle training for other tasks, oversight, and administrative needs.
Requests occasionally come in for training. Each should be assessed individually to determine what is most useful for the individual or team. In the past training has taken the form of one on one tutoring, presentations to groups and hands on training. Work with the requestor to determine what will best meet their needs.
Google analytics collects data on KB usage. As MIT Google Apps does not include analytics in its suite, you must use a personal Google account to access it. This data can be useful to identify popular articles, trends and provide analytic information as needed.
Currently we do not provide the service of collecting and serving analytic data to authors and customers, but they can be granted access to our Google Analytics data to run their own reports.
Admins can add users as authorized users to our Google Analytics property by logging in, navigating to the "Admin" tab, and then clicking on "User Management" in the "Account" column. Be sure add people's personal Google accounts, not MIT Google Apps accounts or they will not be able to access the data.
The archival of any pages in the IS&T website are announced via the #ist-digital-comm channel in the [IS&T's Slack Instance] (internal article, authentication required). Maintainers should regularly check the channel for archival notices ans search for those pages in the KB. If links to archived pages are found, the articles should be updated to point to new locations or remove the information as appropriate. When complete, add a thumbs up emoticon to the post so other maintainers and the Digital Communications Team know the KB has been checked and updated.