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.