Access Keys:
Skip to content (Access Key - 0)

Article style review steps

Things to check when reviewing an article for style and conformation to Knowledge Base Best Practices:

  1. Basics
    • Make sure it is in the correct space. Groups, spaces, Moira lists and permissions in the KB.
    • Click on links to see if they work. If not, correct them. If you can't figure out the correct link, email kb-help@mit.edu or use a feedback button to report the issue.
    • Review the labels. Add any additional labels you think are appropriate. Be sure to include multiple spellings, phrasings and synonyms. More labels are always better for searching.
    • If the labels do not include a category label (generally of the format c-categoryname, determine the appropriate one and add it. For more information, see: What are categories and how do I add an article to a category? Note: Only articles in IS&T Contrib, MIT Contrib, and IST Internal must contain category labels.
  2. Accessibility
    • The Wave toolbar is helpful in finding accessibility errors. http://wave.webaim.org/toolbar
    • Make sure the article starts with an h1. header and {title} macro. Many screen readers use the h1. header as a way to find the main content of a page. The page does not automatically display the article title without the title macro.
    • Make sure any headers are in order. Avoid skipping levels. Don't go from h1 to h3 without h2 in between.
    • Remove tables used solely for formatting purposes. Usually the content can be conveyed by other means. Step by step procedures should not be in tables, only data.
    • Make sure data tables include table header formatting.
    • Make sure all images have appropriate alt text.
  3. Style
    • Spell and grammar check the article.
    • Fix any broken wiki markup.
    • If the article uses the {html} macro, remove those and convert the html to wiki markup.
    • Make sure procedures are in the step/result format.
    • Make sure bullets and ordered steps are being created with wiki markup, not manually.
    • Check image size. If images are too large (over 500 x 500 pixels), shrink them with the width command.
    • Check text formatting to be sure elements are formatted correctly (bold, emphasis, etc).
    • If you have to scroll to read the article and it contains sub-sections, add a Table of Contents.
    • Use your judgment to clean up the article and make it readable. Some ways to do this include: remove excess white space, add tip/warning boxes, break up large chunks of text into paragraphs and create sub-sections where appropriate. If in doubt, review the Knowledge Base Best Practices for instructions and guidelines.
  4. Finishing up
    • Save and view the article to be sure all your changes display correctly.
    • Remove the r-style label. This removes the article from the list of Articles Nominated for Style Review.

The K.B. Handbook

Documentation and information about using The Knowledge Base


Last Modified:

April 19, 2016

Get Help

Request help
from the Help Desk
Report a security incident
to the Security Team
Labels:
keep-me keep-me Delete
label label Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
Feedback
This product/service is:
Easy to use
Average
Difficult to use

This article is:
Helpful
Inaccurate
Obsolete
Adaptavist Theme Builder (4.2.3) Powered by Atlassian Confluence 3.5.13, the Enterprise Wiki