Sunday, May 17, 2009

Microsoft Manual of Style

Microsoft Manual of Style is a bible for programmers to write more accurate, neutral, objective and end-user-friendly documents.

It covers everying we need to know when writing technical documents including writing style, page layout, grammer, punctuation, tone and rhetoric formatting style for number, measurements, date etc.

The best part to me is the "Usage Dictionary".  It lists over 1,000 common words, terms, acronyms and state the proper way to use them, the dos and don't with examples.

Below are some examples I found is very useful and interesting.

active vs. current
        Use active or open, not current, to refer to open and operating windows, programs, documents, files, devices, or portions of the screen (such as an “open window” or “active cell”). However, use current to refer to a drive, directory, folder, or other element that does not change in the context of the discussion.

boot
        Do not use boot as a verb; use start or restart instead, and make clear that start refers to the computer, not to a program. Use turn on to refer to turning on the computer.

crash
        Jargon. Do not use in content for home users and information workers, and avoid in content for software developers and information technology professionals. Use fail for disks or stop responding for programs or the operating system.

debug
        Debug is a valid technical term in content for software developers. Do not use debug in any context as a synonym for troubleshoot. Use troubleshoot or a more accurate word or phrase instead.

default
        Many home users and information workers do not understand that default refers to something that happens if the user does not take an action or does not supply a required value. Consider whether you need to explain the meaning of default in your content or even whether your content can dispense with default altogether.

dialog box
        Always use dialog box, not just dialog, and not pop-up window

e-mail
        Always hyphenate. Do not use as a verb; use send instead.

execute, run
        Do not use execute in content for home users or information workers except to follow the user interface. Use run instead.

illegal
        Use illegal only in specific situations, such as notices on software that say “Do not make illegal copies of this disk”.  Do not use to mean invalid or not valid.

input
        Avoid in all content as a verb; use type or another appropriate verb instead.

interface
        Use as a noun only, as in “user interface” and “application programming interface.” Interface as a verb is jargon. Use interact or communicate instead.

log on, log off, logon, logoff
        Use log on or log on to (not log onto) to refer to creating a user session on a computer or a network. Use sign in and sign out to refer to creating and ending a user session on the Internet.

navigate
        Do not use to refer to the act of going from place to place on the World Wide Web or need on an intranet Web. Use browse instead.

overwrite
        Use only to refer to replacing new data with existing data. Use replace to refer to replacing an existing file with a new one with the same name.

patch
        Do not use; use update instead.

plaintext vs. plain text
        Use plaintext only to refer to nonencrypted or decrypted text in material about encryption. Use plain text to refer to ASCII files.

pop-up
        Do not use as a noun. Avoid as a verb; instead, use a term that more accurately describes the action, such as open or appear.

power down, power up; power off, power on
        Do not use; use turn off and turn on instead. Do not use shut down to refer to turning off a computer.

prompt
        Do not use prompt as a synonym for message. A prompt is a signal, which may or may not be a message, that a program or the operating system is waiting for the user to take some action. Use prompt as a verb to describe the act of requesting information or an action from the user.

purge
        Do not use because of negative associations in ordinary English usage. Use delete, clear, or remove instead.

quit
        Avoid. Use exit instead to refer to the user action of closing a program. Use close to refer to the user action of closing a document or a window. Use close to refer to the action a program takes to close itself. Use log off to refer to ending a user session on a computer or on a network or Internet connection.

read-only
        Always hyphenate.

read/write
        Use read/write, not read-write, as in “read/write permission.”

real time, real-time
        Two words as a noun. Hyphenate as an adjective.

reboot
        Do not use; use restart instead, and take care to establish that it is the computer, not a program, that is restarting.

stop
        Acceptable to use to refer to hardware operations, as in “stop a print job.” Use exit with programs.