Content Best Practices

When preparing content for the knowledge base, articles should adhere to the three goals for content:

• Client-focused: content is relevant, usable, and easy for client to search for and retrieve
• Clarity: content is clear and easy to understand
• Brevity: content is concise and/or linked to external repositories that provide necessary information

Audience

It is important to consider who you are writing for. Consider writing separate articles for different audiences. Answer questions from the client’s perspective, regardless of who the client is.

Article Length

If more than one paragraph is required, consider representing the information using lists or hyperlinks:

• Use Bulleted lists to present a series of options
• Use Numbered lists to present sequential steps or instructions (e.g. How-to’s)
• Use Hyperlinks to embed links to external self-service repositories

Style

All SlugHub content prepared for publication should follow the general rules set out in the UCSC Guide to Editorial Style.

Additionally, it is strongly recommended that all written material in the knowledge base follow the guidelines laid out in the Quick Style Guide which includes a KB template. Adhering to these guidelines promotes consistency and readability throughout the knowledge base.

Creating Knowledge (KB article in ITR)

Once you have your new knowledge contribution ready to go, you can follow our guide to Creating Knowledge, which will walk you step by step through the process of creating a new KB article in ITR. It also includes information about what settings an article should have to be visible to the intended audience.

Search Optimization

Search optimization, as it pertains to the ITS Knowledge Base, is a set of tools and methods used to leverage ITR search results towards the most relevant KB articles. Understanding how the ITR search engine works and the variables that impact search results is vital to an article’s visibility. Once you have published your knowledge, you want to make sure it gets to its intended audience. Please see the article on Search Optimization for full details.

Links

When using hyperlinks, please include some relevant and descriptive text rather than just a raw URL. Try to avoid duplicating content that is already documented elsewhere (e.g. Google support pages), instead insert hyperlinks to existing documents, forms, and knowledge repositories. Do this when:

• The content is already documented elsewhere, AND
• The content will be accessible to the target audience of the KB article, AND
• The linked content is dynamic and up-to-date

Images

When appropriate, use screenshots to provide examples of input fields. Use multiple screenshots to illustrate a series of complex steps, one screenshot per step. For detailed instructions on embedding or attaching files (including images), please see Attaching/Embedding Files.

Attachments

Attachments can include more detailed descriptions, extra information on the topic, forms related to the item.

Please note: If the document you want to attach already exists somewhere else (i.e. an existing repository), please link to it instead of attaching it. Only attach the document if the original repository is not necessarily available to the audience of your article.