Good content starts with clear writing. Deirdre Greene, one of our "go-to editors" and a current contributor on several projects, offers some writing guidelines. In the press to meet deadlines and get things out the door, we often forget that our primary role is to communicate. Good writing is at the center of that goal. Here are Deirdre's tip:
- Always keep the "4Cs" in mind: Be clear, consistent, concise, and correct.
- Identify your writing goal. Many times when someone is explaining a system or a software functionality, he or she gets lost in the details of the system and the reader, who is coming from a different perspective, simply cannot (or even needs to) understand these details. Stay focused.
- Write from your reader's perspective: The majority of people reading documentation will not be system or software experts. That is why they are reading the documentation! The ones who really know the system can navigate without the written words. Be clear in your explanations, taking the reader by the hand as much as possible.
- Separate yourself from the SME. All organizations have a vocabulary that is meaningful only to those in the organization, yet user documentation is intended for people outside the organization. A common mistake among both SMEs and writers is to assume that the user understands the vocabulary. Get rid of organization-specific terms and phrases, replacing them with more commonly used language. Refer to the MS Style guide for the most widely used nomenclature.
- Put information in the correct order. In nonprocedural documents, start with the big picture and then narrow in on the details. In step-action procedures, first tell the user where to do the task, and then tell them what to do. This is called "situating the user." (Many writers first tell the user what to do, and then they tell them where to do it.)
- Incorrect: Select Style from the Format menu.
- Correct: On the Format menu, select Style.
- Don't use "enable": use "you can" instead, and make the sentence active.
- Short descriptions should be full sentences, not fragments.
- Don't use "that are"-in 95% of the cases, the sentence will make sense without it.
- Use "enter," not "type," when talking about entering text.
- Don't use "you need to"-just use the verb (e.g., "You need to turn on the water" should be "Turn on the water").
- Data takes a singular verb (data is).
- Eliminate as much special treatment (initial caps, tags for user input/system output) as possible. If in doubt, err on the side of lowercasing everything and keeping it untagged.
- The one exception to the above tip is when you are writing a procedure with numbered steps that refer to screen elements. In that case, add tags and caps if the treatment corresponds with what is actually on the screen.