TThis article outlines the standards for styling TDX Knowledge Base articles. All articles in the TDX Knowledge Base must follow these guidelines to ensures consistency, accessibility, and quality in the information presented to TDX users.
In This Article:
Writing Content
External Content
Do not duplicate existing articles. Instead, create a curated knowledge article that provides context and explains how users can benefit from the content. Include a link to the original external article. Avoid embedding iFrames to prevent security risks and ensure consistent styling.
Voice and Tone
- Use a clear, helpful, and conversational tone. Write as if speaking directly to the reader.
- Refer to the reader as "you" to maintain a personal and direct tone. Avoid using less personal terms like "user."
- Keep the tone informal and straightforward.
- Be concise: Use short words and sentences, and avoid unnecessary modifiers.
- Be specific: Avoid vague language and unnecessary content.
Sentence Type
Use active voice, where the subject of the sentence performs the action (e.g., "Marti logged into the account"). Passive voice can be used when emphasizing the action over the subject (e.g., "Your account was flagged by our abuse team"). Aim to keep passive sentences below 15%.
Write for the Customer
Consider your audience’s background, goals, and current mood. Ask these questions:
- What is the reader's experience level with the topic?
- What is the reader's goal (e.g., to complete a task, to research)?
- Is the reader in the middle of a task, in a hurry, or possibly frustrated?
Enhance Content Readability
- Avoid using technical jargon that is difficult to understand in articles meant for the public or internal use. If its use is necessary, be sure to explain it in simple language.
- The Flesch Reading Ease score is a widely used measure to evaluate readability. To ensure your article is clear to a general audience, aim for a score of 60 or higher, which corresponds to an 8th- or 9th-grade reading level.
Stay Relevant to the Topic
Focus on the topic at hand and provide links to related content. If you find you’re deviating too much, consider creating a separate but related article.
Keep Paragraphs Short
Keep paragraphs brief (no more than three sentences) and use short, descriptive headings to facilitate scanning.
Formatting Content
Abbreviations and Acronyms
Spell out abbreviations or acronyms the first time you use them, then use the short version for subsequent references (e.g., Network Operations Center (NOC)). For well-known terms like API or HTML, you can use the abbreviation without spelling it out.
Serial Commas
Use a serial comma before the final "and" in a list (e.g., "You need to submit forms a, b, and c").
Line Spaces
Use only one space between sentences.
Ellipsis
Treat the ellipsis like a word, with a space before and after, unless it ends a sentence (e.g., "It’s not . . . fair!").
Em Dashes
Use em dashes without spaces before or after them (e.g., "I saw what I wish now I never—never!—had seen.").
Email Addresses and Hyperlinks
Embed the actual address within the hyperlink text, which should be the title of the linked article. For example, in the phrase "visit the UNC help site," the words "UNC help site" should be a hyperlinked to http://www.unc.edu). Ensure hyperlinks open in the same window to enhance accessibility.
Machine Names
Use normal font for machine names.
Scripts and Commands
Use the Courier New font for scripts, commands, or codes. Use block quotes block for groups of commands.
Numbers
- Spell out numbers if you can do so with two words (e.g., "Nine," "Two hundred").
- Use numerals for larger numbers (e.g., "366," "100,000").
- Spell out fractions unless they contain a whole number (e.g., "Three-fourths," "2 ½").
Images
- Use images to illustrate concepts, locate elements, or confirm settings.
- Crop screenshots to include only relevant parts and use arrows or boxes to highlight key areas.
- Ensure images or GIFs are no wider than 750px.
- Add alternative text to all media for accessibility.
Organizing Content
Article Templates
Use one of the following templates for Knowledge articles:
- FAQ: Responds to customer inquiries in a Q&A format.
- Issue-Solution: Provides information about the cause of an issue and its resolution or workaround.
- How To: Guides customers through specific steps in a process.
- Informational: Documents guidelines and definitions.
Alert Templates
Use the following alert box to address specific scenarios:
Add this Tip alert to highlight information that would enhance the customer experience or be useful to know but it is safe if ignore.
Add this Note alert to highlight situations where there is a lower, but non-zero, chance that failing to follow the described action or information could result in adverse consequences for the outcome.
Add this Caution alert to highlight situation where there is a high chance that failing to follow the described action or information will result in adverse consequences for the outcome.
Article Scope or Summary
All articles must begin with a brief summary outlining the scope of the article, specifying the process, service, or application it covers, the target audience, and its relevance. This should be italicized and not have a heading.
Article Prerequisites
Use the "Before You Begin" H2 heading to mention prerequisites such as technical requirements or access roles needed to follow the instructions.
Table of Contents (TOC)
Include a TOC if your article has multiple H2 headings. List TOC entries as bullet points in normal font under the "In This Article:" heading, which should be bold, in normal fonts, and title case.
Article Keywords or Tags
Tags must be alphanumeric, without spaces or special characters, except for hyphens. An article can have one or more of the following tag types:
- Article Audience (e.g., Students, Faculty, Staff)
- Service Name (e.g., OneDrive, Voice-Services, Adobe-Creative-Cloud)
- Business Application Name (e.g., Canvas, Kronos, Linux, Cisco-Secure-Client, TeamDynamix)
- Abbreviations, Acronyms, or Synonyms (e.g., VPN, TIM)
Article Title or Subject
Create concise, informative titles that are fewer than 10 words and use title case. Avoid using words like "the," "and," "is," or common phrases like "how to." Begin with the software, application, or service name, followed by a colon and a relevant verb in active voice.
If your article is intended for users within a specific major organizational unit (MOU), such as a college or division, prefix the title with the abbreviation of the MOU’s name (e.g., SOP: Screenable).
Lists
For list items, use periods for complete sentences and omit end punctuation for phrases or fragments.
Bullet (Unordered) Lists
Use for items where order doesn’t matter. Use filled-in circles for first level bullets.
Numbered (Ordered) Lists
Use for step-by-step instructions. Limit steps to no more than two related actions.
Nested Numbered (Ordered) Lists
Use for organizing complex instructions or sub-steps. For the first level, use Arabic numerals; for the second level, use lowercase letters; and for the third level, use lowercase Roman numerals.
Combination Lists
Use when a step requires choosing between options. For example:
Tables
Use tables to show relationships between items. Include a caption and a border, and use headers for the first row or column.
Headings
Use headings to organize content and guide users. Reserve H1 for the article title. Use H2 for major topics, H3 for subtopics, and H4 for sub-subtopics. Avoid H5 and H6 unless necessary. Do not use colons at the end of headings.
Managing Content
Article Visibility
Set article visibility to Public, Internal, or Restricted based on the intended audience:
- Public: Accessible to anyone worldwide.
- Internal: Accessible only to signed-in users.
- Restricted: Accessible only to specific signed-in users within designated groups.
Article Periodic Review
Review articles every six months to ensure content remains accurate, current, and relevant. Articles missing their review should be hidden from view.
Article Display Priority
All knowledge articles have the same display priority by default. However, in exceptional circumstances, article owners can request a different display priority using the following rubric, where lower numbers indicate a higher priority:
- Promoted articles (e.g., critical or time-sensitive content): 1–99
- Issue-resolution articles: 100–199
- Informational articles: 200–299
- How-to articles: 300–399
- FAQ articles: 400–499
Knowledge Categories
Organize articles into categories displayed alphabetically. Design top-level categories from the customer's perspective, not based on departments or organizational structure. Ensure top-level knowledge categories align with the service catalog. Use subcategories for services or applications with 15 or more articles. Avoid creating more than three category levels.