About
This checklist is for Knowledge Editors to use when approving internal articles in TDX. See Style and formatting guide for writing Knowledge Base articles for full details on writing and formatting guidelines.
Audience
IT Staff
Details
General Items
- Tags are important piece to each KB; taking time to review those selected and refining them will assist users in finding the articles they need.
- Owners should be set to Groups, not to Individuals to reduce single points of failure.
- The KB Visibility field is used to determine who should be set on the Permissions tab; this field is designed to provide Approvers and Authors confirmation of the desired audience, while the Permissions tab controls the actual security.
- Ensure articles are leveraging the Templates that have been configured; if they do not meet your needs and additional articles could benefit from another type of template, bring that forward to the Process Owners and the Approver group so a new one can be reviewed and created.
Article Title
- Starts with a verb ending in "ing" like "creating" for example. Starting with the application name is an old format.
- Summarizes article contents.
- Uses title case.
Content
- Objective states the purpose of the article.
- Audience is accurately defined.
- Sentences are concise and easy to understand.
- Numbered and bulleted lists are used. No manually typing of numbers.
- There should be no spaces between numbered or bulleted items.
- A note is used if more information needs to be clarified under a step. The word Note: should be bold and red.
- A space should be before and after images and notes.
- Sentences are grammatically correct and contain no typos.
- Refer to the audience as you.
- Information is technically accurate, up-to-date, and complete.
- Acronyms and abbreviations are defined on first use.
- No jargon is used unless understood by intended audience.
Format
- Topic and subtopic titles are formatted as headings.
- Use numbered lists for sequential steps, bullets for non-sequential lists.
- Application interface terms are referenced just as they appear in the interface.
- Application interface terms are in bold.
- HTML is clean.
- Content is in a logical sequence.
- Topic and subtopic titles:
- Use "ing" verbs when describing a process within the article content.
- Are formatted as headings and are not bold.
Links
- Link text is the title of the destination page.
- Do not use "click here."
Images
- Images are uploaded to server (not pasted in or attached).
- Images include appropriate alt text.
- Images are beneath the step(s) they illustrate.
- Images have a TDX-generated 1 pixel border (set in Insert/Modify Image window) to define edges when necessary.
- Images are essential to understanding the content and associated with the step they define.
- Delete unnecessary images. You don't need an image showing a simple button that needs to be clicked.
- Images are cropped and sized appropriately.
- Images shouldn't be wider than 600 pixels.
Settings/Permissions
- Ensure correct category is selected.
- Ensure all fields have been completed.
- Publish to the KB.
- Set permissions selected by the author.
Notes
Knowledge base articles are a great method to communicate information to the campus community and to internal resources that support various services and activities. The TDX KB space may not a good fit for long-term document storage, document collaboration, and detailed service and support documentation. Please work with your supervisor if you have questions around what method to store longer-term project and service related artifacts and information.