About
This checklist is for Knowledge Editors to use when approving internal articles in TDX. The IT Communications team uses Microsoft Writing Style Guide for writing Knowledge Base articles.
Helpful Sections
Audience
IT Staff
Details
Article title
Generally, the subject (title) should begin with a verb ending in -ing:
- Creating
- Configuring
- Viewing
- Adding
- Verifying
Use sentence-style capitalization: Capitalize the first word of the subject and any proper nouns. Otherwise, everything else should be lower-case.
Example: Configuring Office 365 on your mobile app
Writing content
Documentation should be clear and concise. Readers should be able to easily scan the content of an article so they can quickly solve their problem.
- Headings - Using headings to provide structure to your article helps make the article more scannable (Use headings 3 and 4 since the template is using heading 2's already). Headings are under the Format button.
- Lists - Use numbered lists for sequential items. Do not manually type the numbers in a list. Use bulleted lists for items that don't need to be in sequential order.
- Generally, each step should be one sentence. If you need to clarify additional information, that should be done in a note after the step. Note: should be bold and red.
Example: Note: You must use @ksu.edu, not k-state.edu.
- Your sentence structure should start by letting the reader know where you want them to go and what you want them to do.
Example: On the toolbar, click Templates.
- Use the term 'click' (not click on) when you want them to click a button or menu, and use the word 'select' when you want them to select an option from a drop-down list.
- Bold items they need to click or select.
- Bold names of buttons or menu items.
Example: In the Subject box, type your title. Notice the term box is not bold, just the box's name.
- Be consistent when you want them to type something - use type, not ENTER.
- Punctuation should follow the interface.
- Define acronyms with the first use.
Example: Human Capital Services (HCS)
Image Guidelines
Images should be created to show complex processes or something hard to locate on the screen.
Screenshot tips
- Control the size of the image by resizing your window before you take the screenshot.
- Images shouldn't be wider than 600 pixels.
- If your image size is large because of everything you are trying to capture, see if there is a way to break it up. For example, if there are several sections to a window that you are explaining, break your images up into those sections rather than have one large image; You may have three smaller ones.
Highlighting sections of a window
- Use a red rectangle to highlight certain parts of the screen.
- If you are pointing at something, use an arrow and then provide a text description about what you are highlighting.
- If you need to point out a button on a toolbar, take a screenshot of the actual button and surrounding area instead of the entire toolbar.
- Be careful with how much you highlight. For example, using a red rectangle on several spots on the screen makes it hard to tell what you are trying to point out, and it becomes distracting.
Additional Resources
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.