This document outlines the style that all other Tech Support Knowledge Base articles should follow.
Bold text should be used to provide emphasis to specific parts of a document. This could be when alerting readers to a potentially hazardous outcome or when noting that two versions of a product require very different support processes.
Running this script will automatically initiate a restart. Make sure any users are logged off first.
Italic should be used to provide clarity when emphasis is not required.
Select option one if you are doing this for the first time. Otherwise choose option two.
Because underlines are most often used as decoration for hyperlinks, underlining for emphasis should be avoided. Try using bold or italics instead and only underline as a last resort.
Text colors should be used sparingly as they may interfere with themes, are not visible by all, and can often distract from the content.
Headings in documents should not exceed the size of the H2 tag. This means that H1 should not be used. Each heading should have a corresponding html anchor inside the heading tag. When a space is needed in the anchor, an underscore should be used instead (the space is still fine in the heading itself).
<h2><a id='heading_one'>Heading One</a></h2>
By embedding the anchor tag, links can be directed to specific sections of a document instead of just going to the top. There is no way to do this through the WYSIWYG editor, so it must be entered through the text-mode editor. The bold text in the example above is what must be added.
All links to external sites (any link outside of tech.svvsd.org) should open in a new tab or window. The title attribute should be populated. If you are not sure what to populate the title with, use the same text that is being used for the link.
Links to internal documents (those documents stored on tech.svvsd.org) should open in the same tab/window. If linking to an internal document, the link should go to the anchor tag containing the relevant information.
Ordered (numbered) lists should be used when giving explicit directions, such as a step-by-step procedure.
- Open Settings
- Tap Mail, Contacts, Calendars
- Tap Add Account
Unordered (bulleted) lists should be used when listing items in no particular order, such as a list of models affected by a known problem.
If directions do not need to be expanded enough to use a numbered list, click through directions can be used as a short hand. This should be limited in user-facing documents. This should be in the form of item one, space, greater than, space, item two, etc. On-screen selections should be indicated in bold.
File menu > Save.
The use of images should only be limited by common sense. If you think a step by step guide should have an image for each step, go right ahead. Images should be of a decent quality (no 16 color 10dpi). Positioning of images is not limited; if it looks better on the right side of a document, put it on the right.
Alt text must added for all images. Alt text is used by screen readers to describe images to the visually impaired. Images of a purely decorative nature should have the corresponding checkbox selected within the WordPress media editor.
The use of video should only be limited by common sense. Embedded video is acceptable but a link to the source should be placed under the video.
Note: if using an .m4v video file rename with the suffix .mp4
Quoted text should be used when directly quoting an external document or entity. When quoting, ensure you properly attribute the text. It can also be useful when providing asides or examples (all the examples in this document are inside block quotes).
I’ll be quoting Apple support documents. – Michelle Bourgeois
Code snippets should included in code block formatted sections. This will ensure that the code is formatted properly and will space the characters out properly.
This is a code block. Note the easy to read fixed-width formatting.
File and directory names should be placed inside code blocks. This will ensure that the code is formatted properly and will space the characters out properly, making them easier to read.
Always define an acronym before its first use in an article.
Infinite Campus (IC) is the district Student Information System (SIS). IC receives regular updates from the vendor.