Information Technology Services

Submission Guidelines: Help Documentation

• Before Writing
• Document Preparation
• Writing Process
• Technical Writing Standards
• Headings
• Lists
• Tables
• Hyperlinks
• Acronyms
• Graphical Elements
• After Writing

 

Before Writing

• Define the purpose of the document.
• Determine if there is a document already in existence that achieves the same purpose.
• Define your audience.
  • Are you writing to students, staff, faculty, or a combination?
  • What are you assuming about your readers regarding their technical skills?

 

Document Preparation

• The document must be in one of the following formats:
  • HTML
  • Word 2007 (PC)
  • Word 2008 (Mac)
  • text-only
• The file name must be descriptive and contain no spaces.
• Each page must have an introduction or description at the top.

 

Writing Process

• Your instructions should be clear and follow a logical order.
• Avoid using too much jargon unless it is defined.
• Do not use a superior or demeaning tone. These documents are meant to help, not meant to make readers feel unintelligent for needing the help.
• Do not use cryptic or clever titles. Clear and concise is best.

 

Technical Writing Standards

• Use bold type when referring to names of menus, menu options, dialog boxes, buttons, and other named items in the user interface.
• Use italics to indicate a placeholder for information that a user should supply, as well as for book titles.
• Use monospace type to represent code samples, examples of screen text, or text that you would type at a command prompt.
• File name extensions should be in all lowercase.
• Use all capital letters for key names (e.g., ALT, CTRL) and HTML element names.
• Use a plus sign (+) to indicate that you must press keys at the same time in a sequence. Use a comma (,) to indicate that the keys must be pressed one after another.
• Internet, Web, and email addresses should be written in lowercase, unless the address is case sensitive.
• Internet, World Wide Web, and their shortened forms are treated as proper nouns and capitalized.
• When writing notes, the word “note” should be in all caps and bold followed by a colon. The actual note is then written in a regular sentence format.

 

Headings

• The uppermost heading tag (H1) is always Information Technology Services.
• Use heading tags rather than font styles to create sections titles. Start with the tag H2 for the main heading, and follow with H3, H4, etc. There can be only one H2 per page.

 

Lists

• In step-by-step instructions, use numerals to organize followed by lowercase letters if necessary.
• To create indented text underneath a bulleted or numbered point, use the <br> tag, not a <blockquote>.
• When you have a list of links, separate them using an unordered list, not carriage returns (<p> and <br>).

 

Tables

• Only use tables for TABULAR DATA. Tabular data is data that is logically organized in rows AND columns.
• Use a summary with each table.

Example: <table summary="Data Services Committees">

• Use table headers to label the information in the columns and rows.

Example: <th>Committee</th>

 

Hyperlinks

• If the information can be presented concisely on the current page, do not use a hypertext link.
• Give your links descriptive names rather than the actual URL or words such as "click here."

Example: ITS Home Page instead of its.uncg.edu

• Use relative links, not absolute links. A relative link can be used when linking between locations within a Web site. It is created when the href value is relative to the location of the current webpage. An absolute link is one that contains the entire URL.
• Unless you are linking directly to a file, such as a PDF, add a final slash (/) at the end of the path.
• Use anchors to link to information in lengthy documents where scrolling up or down a page is necessary.

Acronyms

You may use acronyms for organization names and terms, provided you write out the full name/term followed by the acronym in parentheses on its first use.

Example: Information Technology Services (ITS)

 

Graphical Elements

• Avoid using too many screenshots. If a dialog box itself provides instruction to the user, just write the instructions.
• Each image must contain a descriptive alt tag.
• Images should be in JPEG, GIF, or PNG format. They should be no wider than 475 pixels and no taller than 400 pixels.
• The official UNCG colors are Navy (003366), Gold (FFCC00), and White. The Information Technology Services (ITS) templates are designed using these colors because our Web pages are considered to be official University publications.
• Background images and colors (other than white) are generally not permitted. They tend to hinder the readability of a Web page. In some cases, a background color may be used to help distinguish between table elements or for highlighting a menu choice.
• Text links should be set to Navy (003366) when not selected, changing to Gray (999999) when selected.

After Writing

• Have another subject matter expert read your document to ensure its clarity and conciseness.
• Give document to Information Technology Services (ITS) Web team for approval and publication.

 

NOTE: ITS requires adherence to these guidelines in order for publication to occur. If you have any questions about the standards above, please contact 6-TECH at (336) 256-TECH or 6-TECH@uncg.edu. A member of the ITS Web team will be happy to assist you.