Target the appropriate audience with the text, vocabulary, technical information, examples, illustrations, and graphics in your documentation. Users of ACS Technologies software and documentation can vary in technical experience. It is better to include information that experienced users can skip rather than omit material that inexperienced users might need.

In general,

• write for a high-school-educated user with no specialized business or computer knowledge.

• assume that the user has basic computer skills.

• unless writing api or other developer content, do not assume that the user has experience with operating systems, programming languages, or developer tools.

• assume that the user has no pre-existing knowledge of the software or the system that you are documenting.

Headings should reflect the mindset and language of our customers, and should not reflect the organization or language of the software.

Each article begins with an introduction. Give users a clear idea of the information that follows and how to use it for the work or task they want to do. The introduction should help users absorb the information you present. For introductions in manuals, provide a brief overview of what the manual is for and why it can be helpful.

To communicate technical information effectively, use short, uncomplicated sentences free of redundancy. Do not try to express too many thoughts in one sentence. Do not begin sentences with lengthy introductory phrases.

Sentences with more than 20 words slow down the reader. Break lengthy sentences into smaller, simpler sentences. Omit unnecessary words to make sentences short, direct, and easy to understand. To shorten sentences, you can reduce the number of clauses and phrases in each sentence. Several relationships in a sentence confuse the user.

Use

• active voice

• present tense

• second person as much as possible

Be sure to define new terms in their specific context. Include abbreviations and acronyms if you plan to use the term again in the same chapter or section of a help file. For each new chapter or section in a help file, redefine the acronym. Be careful not to introduce or use unfamiliar terms without defining them first.

You do not have to define terms that your audience is likely to know before reading the document, such as invoice or general ledger. However, when in doubt, include the definition.

If you introduce an unfamiliar term, define the term clearly and use that same term throughout the manual. If the term has a synonym, you can mention the synonym when you define the term, but only if you think it will help the user to understand the unfamiliar term. As a rule, do not use more than one term to mean the same thing. The user is trying to learn a new system and may think the terms mean different things.

When you make a list of tasks that you want to document, you must distinguish the user tasks from system tasks. For example, the steps in a procedure called "Changing a Member Address" can be identical to the steps in "Editing a Member Record." However, with a slight change in the name of the procedure, the focus becomes different.

"Changing a Member Address" is a task-based procedure because it documents what the user does in the system.

"Editing a Member Record" is a system-based procedure because it documents what the system does with a record.

Diagrams and figures can be helpful in print documents. It is important to avoid presenting too many ideas in a single diagram or figure. The user needs to interpret the information in an illustration easily and quickly. If your illustration is overly complex or cluttered, the reader cannot use it.

Test your diagrams and figures before including them in a document. Typically, a figure or diagram elaborates on and communicates information in the text more effectively. It does not duplicate it.

You can use callouts to communicate essential ideas in a diagram or figure. Be careful not to clutter the presentation. If the reader has to ask even one question about a diagram or figure, you probably need to redesign it. You may need to break up a diagram or figure into several smaller components.

Always choose a style of presentation that is appropriate for the type of information you are communicating and the audience. For example, use links in online Help rather than print documents.

Good examples can do as much to increase user understanding as anything else you include in your content. Coordinate examples with subject matter experts, ux research, or product owners. Do NOT guess about examples. Examples must be relevant and not overused.

When a user needs to perform steps in sequence, you must present the steps in the same sequence. If possible, place notes, cautions, or warnings before the procedure to which they apply.

Notes call the reader's attention to a software feature, a better way of doing something, or a helpful hint. They can also provide information about avoiding a serious mistake.

Be careful not to overuse any of these notes. As a rule, do not use more than one note for every three pages of text.

Avoid using footnotes in most cases, except when citing studies or publications.