Information Technology Services

Submission Guidelines: Information Documentation

• Before Writing
• Document Preparation
• Writing Process
• Technical Writing Standards
• Headings
• Lists
• Tables
• Hyperlinks
• FAQ Pages
• 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
  • PowerPoint 2007 (PC); PowerPoint 2008 (Mac)
• Some larger documents are best in PDF format, such as:
  • Manuals
  • Downloadable forms
  • Policies
• The file name must be descriptive and contain no spaces.
• Each page must have an introduction or description at the top.

 

Writing Process

• 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.
• Use short paragraphs and sentences.

 

Technical Writing Standards

• 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

• Use bulleted lists to break up information in longer paragraphs.
• When the order of the entries is important, use an ordered list. Use the following formatting standard: capital Roman numeral, capital letter, lowercase Roman numeral, lowercase letter. If your list extends beyond four levels, consider restructuring for better readability.
• 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.

 

FAQ Pages

• Standard Frequently Asked Questions pages should contain all questions listed together (by topic if necessary), followed by each question and its answer.
• Link the questions at the start of the document to its answer below to ensure that readers can quickly access an answer to a specific question if needed.
• Limit the number of questions (per topic) to ten or less.
• Title the page "Frequently Asked Question" not "FAQs."

 

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.