Search | Directories | Reference Tools
UW Home > UWIN > Site Information > Guidelines for Publishing 

Organizing and Writing Administrative Web Pages

Definition/Description/Background/Introduction

This document (1) describes the recommended categories for organizing each piece of UW administrative information and (2) suggests a method to help novice procedure writers develop task- and user-oriented pages using the categories.

Administrative information is any information a person needs to complete a business task. It

Categories of Information

We defined seven categories of information to help you break down a given task or support topic. (You may need to create sub-categories and add or omit categories.) We use this breakdown: The procedure is the most important section in a task-oriented document. All the other categories are background information supporting the procedure. On our documents we organize the categories for sequential understanding of the entire topic, but use a bold font for the procedures to provide quick access to them.
  1. Definition/Description/Background/Introduction--general terms describing and defining the information on the page.
  2. Process Overview--general terms describing the activity of other groups and individuals surrounding the procedure/s define on the page.
  3. Procedure/s--describes the exact steps an individual takes to complete the task (Note: The procedure is the most important section in a task-oriented document.)
  4. Common Questions/FAQ--if necessary, a list of questions linked to answers that already exist.
  5. Forms--a list of all the necessary forms either linked to online versions or followed by directions for getting a paper copy.
  6. References/Regulations/Support Documentation--A list of supporting documents, legal or otherwise. Link where possible and give a one or two line description of the resource if it's not obvious from the title.
  7. Contacts--Pointers to people who can help users with the task or topic.

Audiences

Users bring different needs and capabilities when they come to your page with a task. The more you understand them and their tasks, the better you are able to design pages that work. Here is a general breakdown of the audiences for administrative information. (As you meet with your users you can expand the categories and fine tune the tasks for each group.)

Primary Users

Secondary Users

Process Overview

Campus administrative departments use the Web to teach their customers about the tasks and topics in their area. The groups meet with a Webguide and decide:

Procedure/s: Writing an Administrative Web Page

Note: You can print a copy of the Checklist for Writing Administrative Web Pages if you wish.
Complete initial checklist (pdf file)
Create a simple file with the categories listed in order.
  • Use Microsoft Word or a Unix editor if you want to work directly in HTML.
  • Use the simplest formatting that expresses your meaning.
Collect and read the available documentation.
  • Mark any areas you do not understand.
  • Copy the facts you find under the correct categories in your file.
Use the facts to write a very rough draft of the information under each category.
  • There may be many holes in your draft. Do not worry.
  • Put the sentences together in a way that makes sense to you.
  • Do not worry about style or language yet--go for the correct meaning and your own understanding.
Meet with your Subject Matter Expert (SME). Take
  • the documents you collected
  • two hard copies of your categorized information
  • a hardcopy of the document explaining the categories
Ask your SME to read the data you categorized and work with you to correct and expand your understanding of the topic.
Adjust your rough draft to reflect your new understanding.
Show your (still rough) draft to the SME and adjust accordingly.
Observe a few expert users perform the required procedures.
  • Ask the people to tell you what they are thinking and doing as you observe them.
  • Make careful note of the language they use, what they do, and the order in which they do it.
Pull your observations together and adjust your rough draft to include what you learned from observing the expert users.
Share your facts and organization with your Webguide and adjust as necessary.
Work on the title.
  • Put important words near the beginning.
  • Use words that users are likely to enter into a search engine.
  • Be as brief, clear, and accurate as possible.
Organize the Contacts section according to your department's decision.
  • Some departments choose to name individuals and give personal email addresses and phone numbers.
  • Other groups decide to use one group email that does not change as employees change.
Tighten the Definition/Description/Introduction/Background.
  • Decide what to call the category.
  • Ask a few people outside your department to read it and comment.
  • Adjust accordingly.
Finish the Reference/Regulations/Support Documentation section.
  • Decide how to organize it. (e.g., by source, by type, by date, alphabetically--whatever seems to make the most sense.)
  • Check that the titles are correct.
  • List the url for any online source so the HTML person knows what to use as the link.
  • Give a brief description of the content if it isn't obvious from the title.
Polish the process.
  • Remember that it is simply an overview to give the user the context of the procedure.
  • Get the approval of any group you mention. (This may sound silly to you, but you may only think you know what the other group does....)
Write the procedure.
  • Use a checklist format if possible.
  • Describe anything the person needs to get started.
  • Number the steps when the order matters.
  • Start the first sentence of a step with a verb in the present tense when possible.
  • Put warnings before the crucial step, not after.
  • Use:
    • active voice where possible/
    • present tense where possible. (Use passive voice when you want to be intentionally vague.)
    • examples where possible.
    • images and/or graphics where they add value.
    • conditional statements where necessary. (e.g., "If the XXXXX is YYYY, then ZZZZ. Otherwise, JJJJ.")
List the "common questions" if you decide they are necessary.
  • Note where the answer is so the HTML person can put in the correct link.
  • If there are more than 5-7, clump and label them in an effective manner for your users.
Ask colleagues for edit and adjust accordingly.
Ask SME to read your pages and check for accuracy and completeness.
Observe novice users (one by one) following your procedure/s.
  • Tell them:
    • you are not testing them, you are asking them to test the procedure.
    • if they have trouble, it is reasonable that other poeple would also have trouble, and that you plan use your experience with them to adjust the information to make it as easy as possible for people to use.
    • Ask them to tell you what they are thinking as they follow the directions.
    • Please remember to thank them for their time and help.
Adjust your page and send it out to all interested parties for the final review.
Give your file to the HTML programmer.

Forms

References/Regulations/Support Documentation

Contacts