Knowledge Base Best Practices
On this page:
- General Guidelines
- Grammar and Usage Standards
- Formatting Information
- Table of Contents
- Avoid skipping header levels
- When to Use Strong/Bold
- When to Use Italics
- Step/Result Style for Procedures
- When to Use Tables
- Images and Attachments
- Tip, Note, Info, and Warning Boxes
- Displaying Error Messages
- Code, Scripts, Configuration Files, and Command Line Instructions
- The show-to Tag
General Guidelines
Article Creation
- Use the Rich Text editor to create simple text articles.
- For more complicated articles, you may prefer to use wiki markup. For help with wiki markup, see: Notation Guide (Wiki Markup Help)
- Do not copy/paste text into the edit window directly from web pages or WYSIWIG (What You See Is What You Get) editing programs such as Microsoft Word. The editor attempts to process the formatting, and can fail resulting in articles with hidden formatting that is difficult to fix. Copy formatted content into a plain text editor to strip out formatting before copying it into The Knowledge Base.
- Watch articles you create. This provides you with email updates when your article is edited or somebody comments on it. For more information on watches and how to configure them, see Watching Articles.
- Put articles in appropriate spaces. For more information on the spaces in the knowledge base, see Groups, spaces, Moira lists and permissions in the KB
- Documentation being developed for as yet released/announced software and services should be located in the draft space. Articles in the draft space will not be made public as part of normal KB review processes.
- Add category labels to your articles to allow users to find them when they browse by categories. For more information on categories and how to find category labels for your articles, see: What are categories and how do I add an article to a category?
- Put draft warnings on draft/in-progress articles in publicly visible spaces. An easy way to do this is to put the {draft} macro just below the title of your article.
Linking
- For links to knowledge base articles from outside the knowledge base, use the short link located in the right-hand block titled "Short URL for sharing." This link will never change even if the article is moved between spaces or the name changes.
- For links from one knowledge base article to another, use the Wiki Link. When you're logged in, you can see the wiki link in the right-hand block just above the "Get Help" block.
- To create and link to anchors, see Creating and linking to anchors in the KB.
- Do not link directly to IS&T provided software binaries. Link to the Software Grid. This prevents title changes in binaries (which happen with some regularity for minor releases) from causing the links to break. You can use the options to narrow results to just the package you want to link. Then copy the URL from the menu bar to get a link that goes right to what you want, like this one presorted for Mac CertAid: CertAid for Mac
Review Process / Authoring Assistance
- All articles that are created or edited are reviewed by the Knowledge Base team for adherence to this best practice guide and updated to conform to accessibility and style standards listed herein.
- Articles in the IS&T Internal space are additionally reviewed for suitability to be moved to public spaces. Articles that contain individual names and contact information, license keys, internal escalation processes or that contains legally required to be private information will not be moved. If you want to be sure an article is not moved to a public space, please add the {keep-internal} macro to the article to let maintainers and other authors know.
- If you find an article that you believe contains erroneous information, please take steps to correct it or alert the knowledge base team that it is in error.
- If you are able, edit the article yourself or leave a comment on the article that contains all the information you have on the issue.
- If you don't know the right answer, click the "inaccurate" or "obsolete" feedback button and leave whatever information you do have as to what is in error in a comment. This will nominate the article for maintainer review. For more information, see: What should I do if I find an article that has erroneous information?
- If you would like a knowledge base maintainer to review your article for formatting and style (or find an article that could use a formatting and style review), simply add the label r-style to the article. This will add it to a list of articles for maintainers to review and revise per the best practices outlined in this article.
- If you find multiple articles that contain the same or similar content:
- If you are able, edit the articles yourself to merge all the current/useful content into one article and archive the extra.
- Alert the knowledge base team of the duplicate content by contacting kb-help@mit.edu. Where possible, include links to all the articles with duplicate content. Be sure to indicate if any of the content is suspect (incorrect, outdated) and which article you believe to be most correct. A member of the Knowledge Base team will review and merge the articles as appropriate.
- If you prefer to remain anonymous, use the "inaccurate" or "obsolete" feedback buttons on all the duplicate articles, and be sure to indicate in the comment space that the articles are duplicates. The more information you include, the easier it is for maintainers to make appropriate edits.
- To request training in use of the Knowledge Base or assistance or with authoring or troubleshooting specific articles, contact kb-help@mit.edu. A member of the Knowledge Base Team will get back to you promptly to assist with your issue or help you determine what training will best serve you or your team's needs.
Good Behavior
- Do not delete knowledge base articles. Instead move outdated articles to the Archive space. They won't be accessible by customers viewing the knowledge base unless they login; the archived articles can be restored or reviewed later if the information is needed for historical reasons or if somebody is running an outdated configuration. For more information on moving articles between spaces, see How do I move a Knowledge Base article to a different space?
- Do not set page restrictions for viewing or editing articles. The Knowledge Base is designed to be a public, community IT knowledge base. Sensitive or secure information intended for a small audience is likely not appropriate for the knowledge base, and page restrictions are regularly removed from articles in publicly visible spaces. If you are concerned about somebody else editing your article, put a watch on it so you are notified immediately by email about any updates made. For more information on watches and how to configure them, see Watching Articles. If repeated editing of an article becomes an issue or you have concerns about the sensitivity of the information contained in an article, contact the Knowledge Base Team for assistance. For more information, see: [hdarchive:Granular access restrictions in the Knowledge Base].
- Avoid creating Parent/Child pages. Using the "child pages" feature of Confluence is discouraged at this time. In the future, we may change this recommendation, but for now the knowledge base is a flat hierarchy, as it makes it easier to move pages amongst spaces and re-organize the content. If you have a specific case that would benefit from the use of parent/child pages, please contact the Knowledge Base Team.
- Avoid copying and pasting content from the IS&T website (http://ist.mit.edu) into knowledge base articles. This creates a duplicate maintenance problem. Once either page is edited, that creates a version skew and we're sending customers mixed messages. This is confusing and undesirable. Instead of copying/pasting the content into a knowledge base article, create an article with the question(s) and link to the IS&T website page. Be sure to add all relevant labels and possible search terms to make it easy for other users to find.
Grammar and Usage Standards
- Use proper grammar. Site-specific usage standards are outlined below. If in doubt, ask a colleague to review your article or check a grammar reference such as The University of Illinois Grammar Handbook.
- Usage Standards
- WebMail (not Webmail)
- Email/email (not e-mail)
- Hardware:
o Macintosh (not Mac)
o Windows (not Win)
o Linux - Software:
o macOS (not MacOS unless the start of a sentence, Mac OSX or Mac OS X)
o Windows
o Linux - Mobile Devices (not PDAs)
- Web site (not website)
- Home page (not homepage)
- Lincoln Laboratories (not Lincoln Labs or Lincoln Lab, there's a political think tank by that name)
- Use e.g. for examples (exempli gratia - Latin): We use multiple platforms at MIT e.g., Macintosh, Windows, Linux.
- Use i.e. (id est - Latin) sparingly to take the place of "in other words." It specifies or makes a sentence more clear: Jane Doe is the President of a large university in Cambridge i.e., the Massachusetts Institute of Technology.
- When inserting an email address, use a hyperlink instead of spelling out an email address because of spam concerns. Link the person's (or team's) name:
Contact the Knowledge Base Team - Use a hyperlink instead of spelling out a URL: The IS&T Communications Team.
Formatting Information
Table of Contents
- For longer articles with multiple sections, include "On this page" information at the top for ease of navigation. Simply cut and paste the wiki markup below into the top of your article. The table of contents will be automatically generated based on the headers in the article. Any h2 or h3 section headers will have their titles included in the table of contents.
On this page: {toc:minLevel=2|outline=false|style=none}
Avoid skipping header levels
Keeping header levels ordered and consistent is important for creating the auto-generated tables of contents (as described above) and for accessibility. Users utilizing a screen reader frequently navigate pages by the headers. They can easily become lost or confused by a page that uses them inconsistently or skips levels. If there is no h3 sub-header under an h2 tag, the assumption is made that there are no sub-sections within that area. h4 and lower headers may not be found and the user may never know content under those headers exists. For more information, see: Accessibility Tips: Avoid Skipping Header Levels
When to Use Strong/Bold
Do use strong/bold formatting ( *strong text* ) to designate:
- Buttons: Click the Submit button; Select the Yes radio button.
- Drop-down menus and items: Select Many from the Options drop-down menu.
- Paths: Go to Firefox > Services > Finder.
Be sure to leave spaces between the words and the > so screen readers (and other users) can easily interpret the text. - Checkboxes: Select the User and Administrator checkboxes.
- Notes, Tips, Warnings: Note: This software is no longer available.
- Tabs: Clickable tabs should appear in bold: Click the Control tab to go to the next screen.
o However, do not bold if it is simply in reference to the name of the tab: The Control tab appears at the top of the page.
Don't use strong/bold formatting:
- As a sub-header.
- To designate Window or dialog box names - Use italics instead.
When to Use Italics
Use italics formatting ( _italic text_ ) sparingly, but always for the following:
- Result of a step in a procedure.
Click the Okay button.
Result: The Options dialog box appears.
- Window, screen, or dialog box names:
Result: The Where do you want to install Windows? dialog box appears.
Step/Result Style for Procedures
This style for procedures makes it easier for end users to follow along with the steps and to know they have completed them correctly.
- An example of the Step/Result format:
1. From the Start menu, choose Control Panel.
Result: The Control Panel window opens.
screenshot image here, if required
2. Click Network and Internet.
Result: The Network and Internet window opens.
screenshot image here, if required
When to Use Tables
Use tables sparingly. Tables used for formatting are difficult for screen readers and other accessibility devices to interpret properly. Think about whether a list would be sufficient - or simply use carriage returns. For more information on tables and accessibility, see: Web Content Accessibility Guidelines 1.0: Guideline 5 Create tables that transform gracefully.
Note that the {section} and {column} macros will insert tables into your page when they render your content, so the same caution applies to using these macros to create a multi-column page or section.
Images and Attachments
- Avoid using screen shots for obvious buttons in procedures, e.g., Next, Continue, OK.
- Keep images as small as possible, but be sure to maintain readability and context. Generally 400x400 pixels is the maximum desired size so that images will fit on the page without scrolling and not be disruptive the flow of the document. You can crop images to show only the relevant portion of the screen or shrink the image to achieve your desired image size. For instructions, see: How do I insert an image into my article?
- Alt Tags: Alternative text provides a textual alternative to non-text content in webpages and is necessary for all images in the knowledge base. Screen readers and other accessibility devices can't interpret images without alt text.
- Every image must have an alt attribute. For instructions on how to add an alt attribute to your image see: How do I add alt text to images?
- Alternative text should present the CONTENT and FUNCTION of the image and it should be succinct.
- Alternative text should not use the phrases "image of..." or "graphic of...". The user already knows it is an image.
- Alt text of a functional image (e.g., an image within a link) should describe the function as well as the content.
- Decorative images require a null attribute (alt="").
- Important: If you find that you are struggling with the text you should attribute to your image, ask if the image is actually necessary. We encourage authors to limit images when descriptive words suffice and will edit or remove images and tags that are not consistent with the site format or distract from the webpage's intended, helpful content.
- For information on what to put in your alt text, see: Appropriate Use of Alternative Text
- Images and other files are stored as attachments to the specific article. For instructions on adding one to your article, see: How do I add an attachment to an article?
- Note: Do not share attachments between articles. Attach each image you want to use in an article to that article, even if it is already attached to another article.
- The maximum attachment size is 2MB. If you have larger files that need to be hosted, consider storing them in another location, such as a publicly readable AFS locker. Even though they aren't uploaded directly to the Knowledge Base, you can still link to them from your article.
Tip, Note, Info, and Warning Boxes
Use sparingly; opt for the bold format for minor notes and tips. When products or services are undergoing major changes in functionality, support or availability, a support notice placed on pages related to that product or service is a good way to keep customers informed of the upcoming changes. For more information, see: [Support Notices].
Tip: These tip, note and warning boxes are specified by wiki markup. Simply put the {tip}, {note}, {info}, or {warning} markup tag on each side of the text you want included in the box. |
Note: This is a shared knowledge base. Other authors may edit your articles. You can track changes to articles you create by putting a watch on them. For more information about watches, see Watching Articles. |
Category Tags Adding category tags to your article allows users to find it when they browse the knowledge base categories. For more information, see: What are categories and how do I add an article to a category? |
Warning: Do not delete knowledge base articles. Deleted articles can not be restored. Instead move outdated articles to the Archive space. They won't be accessible by customers viewing the Knowledge Base, but they can be restored or reviewed later if the information is needed for historical reasons or somebody is running an outdated configuration. For more information on moving articles between spaces, see How do I move a Knowledge Base article to a different space? |
For instructions on creating these boxes, see: How do I add tip, note, info, and warning boxes to articles?
Displaying Error Messages
Display error messages using the quote style or a screen shot. Note that text in screen shots is not searchable, so it is still desirable to include the text of the error message somewhere in the article or keywords to make it easy for customers to find it.
- Quoted error message:
Use the {quote} markup tag for quoting error messages.
Photoshop 12.0.1 update for Photoshop CS5
Updates cannot be installed on keyed products using the Adobe Application Manager. Please contact your Sassafras Administrator for more information.
For more information, see: How do I quote text in articles?
Code, Scripts, Configuration Files, and Command Line Instructions
For displaying a single line of instructions or text to be entered in the command line or a configuration file, you can use mono-spaced text or the gray boxes described below. Mono-spaced text is best for including instructions within text or short examples that don't need the box to highlight them as a separate type of content.
- Instructions on a separate line example:
pine --install-local-config
- The wiki markup looks like:
{{pine --install-local-config}}
- Instructions included in text example:
To check the print queue of Ajax, enter lpq -Pajax at the prompt.
- The wiki markup looks like:
To check the print queue of Ajax, enter {{lpq -Pajax}} at the prompt.
If you need to emphasize a single line or display more than one line of information such as programming code, shell scripts, or text from a configuration file, use the {noformat} or {code} markup tags. Both result in gray boxes. The {noformat} style displays the text exactly as you enter it in a mono-spaced font. The {code} style automatically formats code and allows for additional formatting within the box.
- Code formatting:
- Command line instructions with {noformat}:
add weather weather -f bos
- Command line {noformat} example with results:
athena% lpq -Pajax Printer: ajax@paper-pusher 'HP8000 W20-575' Queue: 3 printable jobs Server: pid 27313 active Unspooler: pid 27531 active Status: printing data file 'dfA995w20-575-16.mit.edu' at 13:23:24.071 Filter_status: device = 'Ready Online' at 13:23:37.539 Rank Owner/ID Class Job Files Size Time active joeuser@w20-575-16+995 A 995 abstract.PS 8069 12:20:22 1 janeuser@w20-575-1+432 A 432 thesis.ps 17239 12:23:19 2 bobuser@w20-575-3+782 A 782 21W.575.doc 173564 12:24:52
For more information on creating these boxes, see: How do I add code and noformat boxes to articles?
The show-to Tag
- We recommend against using the {show-to} tag as Service Now does not support this functionality and sensitive data could be exposed when content is migrated into the system.