L&S Administrative Gateway Document Style Guidelines
L&S Administrative staff who provide content for the Administrative Gateway should follow the guidelines provided in this document.
What is the Administrative Gateway?
The L&S Administrative Gateway is a new way to provide L&S departments, programs, and administrative staff with information they need to do their work. This is a searchable database of information about the policies and procedures we use to make the College of Letters and Science run smoothly and effectively.About Administrative Gateway Documents
Authors
In general, the people who are preparing these documents are the people who are closest to the information. Each unit in L&S Admin should have an individual designated to work on the Administrative Gateway information. Questions and comments can be directed to these individuals, who will have the ability to update documents and add new documents as the need arises. The plan is for this tool to be responsive and easily updated.Style Guide for Authors of Administrative Gateway Documents
As you work on your documents, please keep the following standards in mind:- See the KB User's Guide - Documents Tab - Document Style Guidelines for useful guidance on creating and editing documents. In general, we'll adhere to these conventions, since most users of the Administrative Gateway will be accustomed to the KnowledgeBase environment (which is what we're using for the Gateway)
- All documents and attachments in the Administrative Gateway, including files saved in Word, PowerPoint, Excel, Acrobat, and other formats, must comply with the UW-Madison Web Accessibility policy. See Document 61917 is unavailable at this time. for information about the policy, resources, and tools.
- In short:
- File your document in a reasonable location, using sensible topics. We're still building the topics hierarchy; if your section has topics, use them. And yes, one document can have multiple topics. Cool, eh?
- All "External" documents should also be available in the "Internal" site. The reverse doesn't need to be true, but always do this please - otherwise, people who are on the internal site won't be able to find your pages.
- Give your document a clear title. It should be short, accurate, and sufficiently descriptive. (Remember, the search feature looks for keywords and titles, so the terms you use here will also be helpful for searching.) Don't be afraid to use titles with "How to..." or "How do I...?", since your audience may be thinking in those terms, too.
- Keywords should be standard terms: service or process names, key concepts, synonyms, and acronyms. Title words and words from the summary are automatically included so there is no need to repeat them here.
- Summary statements should be short - two to three sentences, at the most.
- Use standard Header formatting (H3 and H4 only) (under "select header" in the WYSIWYG screens) to organize subsections of your document. Since your documents shouldn't be very long, two levels should be enough. If you need more levels, consider whether or not you need multiple documents. Using header formats helps people who use screen readers to move from section to section - so please don't use header formats just to change font size!
- Get rid of excess HTML coding. If you're copying from other web documents or from MSWord, it's easiest to copy your text, paste it into a text editor (Notepad) that will erase all of the hidden codes, then copy and paste it into your Gateway document.
- Seriously, get rid of those ugly, excessive formatting codes. If you don't, they will mess up your font and make your document really ugly. If you're copying text from just about any other program, do this:
- Select text and copy.
- Paste into Notepad.
- Select the text in Notepad and copy it again.
- Paste into your Admin Gateway document.
- Proofread what you produce. Check spelling, links, etc. Remember, the quality of this document is a reflection on the College, on L&S Admin, on your office, and on you. Take care to make a good impression.
- Keep it short. Aim - if possible - for "chunks" of information about the size of one computer screen.
- Security matters. The L&S Administrative Gateway is not intended to be used for purposes of sharing restricted data. Please refer to the Division of Information Technology's website for information about restricted data (https://it.wisc.edu/about/office-of-the-cio/cybersecurity/security-tools-software/restricted-data-security-standards/) - in essence, users should not post any documentation that includes the types of information listed below.
- social security number
- driver’s license number or state identification number
- financial account number (including credit/debit card) or any security code, access code of password that would permit access to an individual’s financial account
- deoxyribonucleic acid profile as defined in S. 939.74 (2d) (a)
- unique biometric data, including fingerprint, voice print, retina or iris image or any other unique physical representation
- protected health information (any information about health status, provision of health care, or payment of health care
Good practices
- Every document in this space is provided for other readers, so what you write should be written with your reader in mind. Often, you will be writing for people who are new to the college or university, so you should write for novices, not experts.
- It never hurts to ask someone else to read what you've written. You can submit your work to the team, or ask for someone in particular to review your work. (If you have a co-worker who may be your best editor, let us know and we can grant access to that person, so he or she can review your work.) Several people in L&S Admin are always happy to improve communication - Elaine Klein, Megan Costello, and Sarah Morton will be happy to read drafts and suggest ways that a document could be improved.
- When you create a document, it is a "work in progress". When you're ready for the team to review it, place it in "team review" to get feedback. When it's ready to publish, it needs to be changed to "active". (And, to take it offline, it needs to be marked "inactive".)
- While some documents may be "internal" only, I believe we will use this infrequently.
- Remember that every document has a "feedback tab" - your readers will be able to weigh in on whether your document was useful or not, and many will give feedback. We'll conference about how to deal with feedback as we receive it, but it's never a bad idea to take good advice. And it's usually a bad idea to perceive "advice" as personal criticism.
- Use the Glossary to unravel jargon and special words that are used in your area. (My rule of thumb: inside South Hall, "STS" means "short term staffing"; outside South Hall, it means "Science and Technology Studies". Go figure!)
- If you want to include an e-mail address in your file, you may want to avoid embedding a link (to avoid spam). Consider, instead, using the convention of "name<at>place<dot>institution<dot>edu" . Most people know to replace the <at> with "@" and and <dot> with periods.
Workflow
Authors create documents, submit them for review, and either Elaine or Sarah will publish them. (We expect that this may change in the future; however, during these first few months, we'd like to have extra eyes looking for sensible prose and weeding out typos...)