Lists, when used correctly, can be a technical writer`s best friend – and a reader`s. Lists allow you to highlight important ideas. They also increase the readability of text by simplifying long sentences or paragraphs and adding aesthetically pleasing passive space to make reading more enjoyable. However, using the wrong type of list or formatting a list can cause confusion rather than improve readability. Therefore, it is important to understand the different types of lists and understand how and why they are used. The second bullet in the list above contains two “or”. The article is long and complex. A better approach is to eliminate the “or” with a nested “the following” clause. NOTE: The 4 steps in the numbered sample list each begin with a verb (review, review, edit, and proofread) that specifies what the reader should do, and the numbers indicate the order in which these steps should be performed. Use numbered lists when the order of the items listed is important and ideas should be expressed in chronological order.
For example, use a numbered list when you need to list a series of steps in instructions or when you present ideas that are explained in a specific order in the following text. If you have a list of more than 8 items, you must divide the list into two or more phases or categories (steps at level 1, steps at level 2, etc.). Punctuation conventions for list items vary depending on the context. Legal writing tends to use more punctuation than technical writing (list items often end with semicolons and the last item is preceded by an “and”). Because this style promotes simplicity, in technical documents, you usually place an item after the last item in your list. If each item listed contains complete sentences, place a period at the end of each list item. If you have a simple bulleted list, you can omit the last item. RuleSpeak recommends avoiding words at once and either in lists with only two bulleted conditions. The reason for this is that if additional bullets are added later, the meaning of “both” or “either” is omitted.
Natural language generally makes no assumptions about whether an “or” should be exclusive or inclusive. The ambiguity can, of course, be eliminated by explicitly stating “exclusive” or “inclusive” in each case. For business rules, however, tabbing is usually much more efficient. Use a labeled list when listing items that require further explanation. These can be bulleted or numbered. Start the list item with the word or phrase (the label), italics (or bold), followed by colons. After the colon, write the explanation or extension of the term or concept in normal running text. Tabulation can be used in some cases to unify business rule statements that could stand on their own. [4] Such unification eliminates the fragmentation of business logic that might otherwise occur. It also provides central coordination points for associated business rules to ensure they can be found, reviewed, and possibly revised together. All correctly expressed business rules in RuleSpeak are declarative.
Note that in the revised version of the example above, tabular conditions are bulleted rather than numbered or labeled (as was the case in the previous contract example). When creating lists of any kind, keep the following guidelines in mind: A “nested” list is a list within a list or a list of child items. These can be useful for avoiding excessively long bulleted lists by categorizing items into sub-lists. Note that the long bulleted list on the left doesn`t effectively categorize items, so the focus is lost. The nested list is more efficient. Does the statement mean exactly one or at least one of the three points listed? Different readers may make different assumptions. Suppose at least one is planned. This commercial statement could be interpreted to mean that a particular shipment can only be made in the two countries listed.
Sending the same shipment to both countries is almost certainly not planned. This is not an exhaustive list of the types of lists you may encounter during your technical reading. These are simply the most common types of lists that you need to identify and use effectively in your technical writing tasks to improve readability. In some cases, a list may not be useful and complicate your document. In such cases, list your ideas as a sentence in the paragraph, as in the last panda example below. A page with too many lists looks like an outline rather than a coherent set of ideas. NOTE: If you create lists by pressing ENTER, then TAB, and then a hyphen, you do it wrong, which will make future editing and maintaining readability very difficult, if not impossible. Especially if you`re co-authoring documents that require thorough review and editing, you need to make sure you`re using the right formatting tools. There are important reasons to use tabulation when writing business rules.
It provides a structure for both thinking about business rules and shaping them in a way that is naturally suited to ask questions and identify ambiguities, gaps, and inconsistencies.