In this article
Follow the steps below (in this order) to review an article.
Testing
- Make sure there is a Configuration Item.
- Go through the steps to ensure validity.
- Fill-in-the blank for missing steps.
- Remove steps that are not needed.
- If don't have access or cannot check the steps, reach out to the Content Owner.
Top
Formatting
- Need Table of Contents if there are more than 2 subheadings.
- Use Anchor tags in TOC.
- Need for Top tag if the article has more than 2 subheading.
- H2 tags needed for In this article and subheadings.
- In this article and subheadings: Only the first word is capitalized.
- Short Description: All words in this title need to be capitalized.
- Short Descriptions format: Action + System. No need to start with How to.
- Identify Ordered and Unordered list.
- Bold Action words.
- Check links for any broken or incorrect directs.
- Make sure the internal hyperlinks have this format: https://itsupport.umd.edu/itsupport?id=kb_article_view&sysparm_article=KB00XXXXX.
- The title of the link should be the title of the page it's going to.
- Use acronyms only when the word has already been mentioned in full with acronyms in parenthesis.
- Check line breaks (<br/>).
- Check the Source Code (<> icon) to make sure it looks clean and doesn't contain any extra formatting/html tags.
Top
Images
The image review process can include one or all of the activities listed below. For complete details about the image review process, see the Reviewing Images in the knowledge Base article.
- Removing images.
- Contacting the Content Owner.
- Removing attachment.
- When to correct images.
- Editing images.
- Uploading and adding images to articles.
Top
Style
The editor's order of operations
- Read the text. Do not edit it. Get a feel for it, where it's going, what it's about and so on.
- Apply a fine-toothed comb. Fix typos, punctuation, usage and grammar mistakes. Fix style mistakes. All articles must follow the Knowledge Management Style Guide. Where the Knowledge Management Style Guide has no guidance, default to AP Stylebook. Review technical terms and jargon; any new terms must be brought to the attention of the team for review.
- Look at the big picture. Does the structure of the text make sense? Is the information in the right order? Does it flow from one idea smoothly? Is everything clearly explained? Does it have any unanswered questions or missing information? Almost all articles should answer the basic questions: Who, what, when, where, why and how.
- Fact-check everything. Verify all names and titles. Check dates. Check that links work.
- Revise. This is done whenever new information is added and can include: removing redundancies, trimming wordy text, making sure that no other editing introduce gaps in the article.
Considerations
- Knowledge Management follows Plain Language guidelines. Does this article?
- Understand when to consult a supervisor or the subject matter expert. When in doubt, consult.
- Align jargon and technical terms with Word Usage and Consistency List. If the article introduces any technical or jargon terms not found in the Word Usage and Consistency List, they should be brought to the attention of the team for discussion and potential addition to the list.
When to consult a supervisor or subject matter expert
Adapted from Copy editing protocols by Nick Juliano (links to a downloadable PDF).
Changes in which a consultation is not required:
- Correcting a misspelled word.
- Correcting and obviously misspelled name, title or application.
- Making minor cuts for a more concise article.
- Correcting most violations of the style guide. Exceptions that serve a specific purpose may be accepted.
- Remediating accessibility issues, unless they require significant changes to the article.
Changes in which a consultation is recommended:
- Filling an information gap in the article. Significant gaps require a consultation.
- Moving a section.
- Minor changes to an image, including: cropping.
Changes in which a consultation is required:
- Making major cuts or additions.
- Retiring an article.
- Reconciling inconsistencies with other articles.
- Major changes to an image, including: removing.
Top
SEO
These are the main tasks performed when reviewing SEO for a KB article.
- Create or revise the meta of an article. This may include search analysis.
- Write or revise meta-description.
- Add, create, or revise system tags.
Top