This is the WIP document to create style guidelines for TDX Articles and Services. This will serve as a rubric, and deeper instructions will be housed in Composing TDX Article - Tips and Tricks by Chance until a proper guide is built.
Formatting
All items should be written directly in the TDX Editor, copy/pasting information is an option, but be sure to fix any formatting issues that may arise from this process.
Structure
All Articles should follow a simple structure. Outlined below:
Articles should begin with a Heading 2 to act as state of intent for the whole article. This can be called "Question" with a question the users would ask that would be answered in the document. It could be called Contents if started with a table of contents. Avoid repeating the name of the article, as it will be at the top of the page when viewing, but not when composing.
Further heading should be broken up into simple categories. This will depend on the process or information being displayed, but keep your heading bodies concise. Do not bloat your bodies, and do not overfill your information. If you have to spend more than ~250 words, consider simplifying your breaking up your documentation. (For reference, this subheading Structure is 200 words).
The final heading should be a Heading 2 which instructions on what to do if the user has further questions, comments, or needs assistance. This should be somewhat unified for your department to ensure the correct information is being given to all users. This can be done in a "More Information" or "Need Further Assistance?" section. (See E-mail Cloud Migration - FAQ, Troubleshooting & Common Solutions for an example of this)
Headings and sub-headings
There are a few built-in heading available in the TDX Editor. Heading 2 should be used for all top-level headings. Headings 3, 4, & 5 can be used as sub headings. If you need more sub-headings than that, you will need to simplify your documentation.
Lists, numbers, and bullets
When creating lists, ensure the list is not too long (~10 items). If so, make the list into a table, graphic, or something that will not take up as much vertical space.
Bulletted lists should be used when the order does not matter, and the information does not require as specific process or steps.
Numbered lists can be used, and the order of sub-headings should be as follows. If you need more sub-levels you will need to simplify your documentation. See the Tips and Tricks articles on how to do this because TDX does not set it as a default.
- Numbers
- Lowercase Letters
- Lowercase Roman Numerals
Text Formatting
Normal text should not be altered from the TDX defaults. There are a few exemptions to this rule, and will be outlined below:
Important links to other pages can be added. (see Working Remotely - FAQ and Best Practices for and example of this). Linked text like this should be formatted as follows (The underlining comes from it's status as a hyperlink):
- Font Size 18
- Bold
- Center Aligned
Warning text can be added as fully bolded sentence, and can be bulleted if inside a list. Otherwise the bolded sentence should be its own paragraph. (See How to use and configure GlobalProtect (Mac) as an example of this).
Keywords should be placed in bold. Keywords are any of the following:
- Text that is inputted by the user
- Items clicked, tapped, or selected
- Items user is directed to both in the article or in instructions
Example: Click Continue, and input your WesternU Email Address (Example@westernu.edu). Bolded items indicate an action for the user.
Messages and alerts should be placed in italics, bolded, and colored Fire Brick Red. Anything that the user will see, but not click or directly interact with should be made into this style.
Example: If you receive the message This site is not secure continue with Step 5.
Links
Links should be inputted when necessary in your document, whether they be do a different article, or an outside page. When adding a link, be sure to edit the hyperlink and select New Window in the Target tab to ensure the user does not lose the page they are reading. This is not a default, and will need completed for each link.
Pictures
Pictures should be used at a minimum as they are not helpful for users that require screen readers, and can cause formatting issues on different displays (Mobile, smaller screens, Etc.). If a picture is included in your document, the information it displays, and instructions it pertains to should be fully written out in such a way that if the pictures were not part of the document, the users can complete the process anyways.
After or during adding a picture, add a sentence describing the picture in the Alternate Text box. This is what screen readers will read off when used on the web page. This should be completed for each picture added.
Language and Composing
This section will outline the proper language and context that should be used when writing articles.
Write for the User
All documents should be written from the perspective of the user. This means using information the User will see, and using basic terms that a user would know. Refrain from internal terms, lingo, and slang as these articles should be understandable by everyone who reads it. Write documents in such a way that a user who has never seen the process before can complete it.
Abbreviations should follow this format: Long Form Name (Abbreviation). You can then use the abbreviation in the article as normal. If your document is long, repeat this step on the first mention of each Heading 2.
Unified Language
System functions should use unified abbreviations, see list below:
- Control: CTRL
- Windows: WIN
- Alt: ALT
- Option: OPT
- Command: CMD
- Function: FN
- Delete: DEL
- Backspace: BACK
When writing out combinations of keys, use a plus symbol and it's abbreviated name (CTRL+ALT+DEL)
Other actions should also be unified, see list below:
- Click: Clicking on items
- Tap: For instructions pertaining to mobile devices (phones and tablets)
- Select: When selecting options (like radio buttons, dropdown menus, Etc.)
- Check: For checkboxes in items
- Scroll: To scroll up/down a page on a computer
- Swipe: To scroll up/down on a page pertaining to mobile devices (phones and tablets)
- Double-Click: Self-explanitory
- Long Press: For instructions pertaining to mobile devices
- Right-Click: Self-explanitory
- CMD+Click: Mac specific, some instructions will require this
- CTRL+Click: Self-Explanitory
- CTRL+Right-Click: Self-Explanitory
Key combinations should have no spaces, and use a plus ( + ) sign to indicate a combination.
Avoid using terms outside of this list, as it will keep a unified language for actions for all users reading documents.
Use K.I.S.S.
Use KISS to keep things short and sweet. KISS stands for Keep It Simple, Stupid. Meaning you should remove unneeded information and bloat from your documents. Bullets and lists do not need to be full sentences, and full sentences should not run on. Keep only the information that it vital to the user to understand, resolve, answer questions they may have.
Finalizing the Article
There are a few steps to run through when finalizing your article.
Subject, Summary, and Tags
The subject should be short and sweet, but clearly states what the article is about. The summary should contain a short (less than 100 words) summary of the article and it's contents, include information here on the issue in longer length, as well as who may be using the article.
Tagging an article is vital to ensure the users can find it via a quick search. There are a few tags that should be included regardless of the article content, outlined below:
- WesternU to allow the Google Search algorithm to find the article when users search
- Students/Staff/Faculty: Include all relevant tags for the user(s) that are expected to use the document
- Applications: Tag any applications that are included in the process (Office365, Outlook, SPSS, Zoom, Etc.)
Do not be afraid to use too many tags, but keep them relevant. Note that tags cannot contain spaces, and as you type the box will show tags used in other articles, use these if they show up as it will help unify the tagging system for easier searching.
Article Placement and Anchoring
Make sure your article is nested into a correct, and relevant, category. If an article should be in multiple places, notify an admin so have it linked in those categories as well. This allows the article to be edited in one place, and all places it is linked will update with it. Admins will see an Anchor symbol next to these linked articles, but the users will not, and it will appear as a normal article to them.
When an article is created, it is given a URL that does not change, even if the article is completely changed and moved, the link will not change. This is helpful for living documents such as changelogs and processes that continue to change. This also allows you to continue to use the same link throughout the life of the article, helpful for bookmarks and quick replies to users.
Adding Attachments
You can add documents/attachments to articles. Documents added to the sidebar should either be directly related to the information, and should not include any information that is not already part of the article. Exceptions would be long-form documents that are multiple pages, or forms that need downloaded, filled, and signed. If this is the case, note inside the ticket the process of downloading the file and what needs to be completed within it.
Related Articles
If your article contains processes or information included in other articles, link them in the "Related Articles" section. If you include links inside the article to other articles, include them here as well. This will help users find all relevant information to assist them in self-resolving or finding info they need.