Information Technology — Configuring Software @ Rhodes

Style Guidelines for Writing Config Instructions

• Start your page with a level two heading (i.e. !!). A level one is already provided by the template.
• Write in full, English sentences. Don't use slang, or make assumptions that the readers will "figure it out".
• Check your spelling. If you use Firefox, you can do this quite easily by installing a dictionary. Remember that South African English is closer to British English (en-GB) than US English (en-US).
• Quote what you see on the screen exactly. If the menu you want to refer people to is called "Connection", don't send people to the "connextions" menu. Make sure you match case and punctuation (e.g. "Tools...").
• Use italics for stuff people can expect to read on the screen. For example: "Click on the Connection Settings button."
• Use bold for stuff people need to type in. For example: "Type wwwproxy.ru.ac.za into the Proxy: text box".
• Make sure your instructions tell people how to save their changes.
• If you upload images, make sure that their naming doesn't clash with existing images. A good way to do this is to prefix your image names with something that identifies what page it fits into.
• People assume that instructions refer to the Windows versions of programs. If you're writing instructions for some other operating system, mention it in parenthesis after the application (as in "Safari (Mac)").