Search | Directories | Reference Tools
UW Home > Discover UW > Site Information > Guidelines for Publishing > Writing Administrative Information 

Checklist for Writing Administrative Web Pages

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.