Author or Editor: Michael George - Edit

Support Document Style Guide

This document outlines the style that all other documents on this site follow.

Bold

Bold text should be used to provide emphasis to specific parts of a document. This could be when alerting a reading to a potentially hazardous outcome or when noting that two versions of a product require very different support processes.

Note that running this script will automatically initiate a restart. Make sure any users are logged off first.

Italics

Italic should be used to provide clarity when emphasis is not required

Color

Colored text should be used sparingly.

Headings

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.

Links

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.

External Linking Guideline

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.

Internal Link Guideline

Lists

Ordered (numbered) lists should be used when giving explicit directions, such as a step-by-step procedure.

  1. Open Settings
  2. Tap Mail, Contacts, Calendars
  3. 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.

Models affected:

  • T5500
  • T5510

Click through directions

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. 

Images

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.

Video

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

Quotes

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). The block quote icon can be found on the top row of the WYSIWYG editor (icon is a double quote) or in the text-mode editor (button says ‘b-quote’).

I’ll be quoting Apple support documents. – Michelle Bourgeois

Code

Code snippets should included in code block formatted sections. Code block is only available from the text-mode editor (button says ‘code’). This will ensure that the code is formatted properly and will space the characters out properly. The code block sections tend to get automatically cut off if blank lines are detected. This means you should either remove blank lines or put something on the line to keep them from being blank like a comment character.

This is a code block. Note the formatting.

Filenames

File and directory names should be placed inside code blocks. Code block is only available from the text-mode editor (button says ‘code’). This will ensure that the code is formatted properly and will space the characters out properly, making them easier to read.

C:\Windows\Temp

Last updated by black_erik on 2015-04-07 16:00:30

Comments are closed.