Rules for Structuring Lists in Technical Documentation
Lists strike an effective balance between linear prose and tables for organizing information. Use numbered lists for sequential actions where order matters: installation steps, algorithms. Use unordered lists for collections of items without a strict sequence: parameters, components.
Keep lists to a reasonable length. Lists spanning hundreds of lines are hard to scan—break them into subsections or tables.
Lead-in Phrase as a Guide
Always use an introductory phrase before a list to define its contents. It provides context and ties the items together.
Examples of lead-in phrases:
- Perform the following actions to initialize:
- Main function parameters:
- Required system components:
Rules for forming them:
- Place a unifying term (actions, parameters, steps) near the end.
- Avoid specifying the number of items—it can become outdated with changes.
- If a specific term doesn't fit, use generics: item, part, step.
This ensures consistency and makes the text easier to scan.
Noun Phrases for Consistency
Phrase list items as noun phrases. This creates a uniform structure and improves readability. Example transformation:
Incorrect: The process consists of: blanking, preparation, shipment.
Correct: The process consists of the following steps: blanking, preparation, shipment.
All lines should be grammatically consistent, without mixing sentence fragments and full sentences.
Avoid Repetitions in Items
Repeated words at the start of list items create a parrot-like effect. Move the common word into the lead-in phrase.
Example:
Incorrect:
- Library A
- Library B
- Library C
Correct: Install the following libraries:
- A
- B
- C
This shortens the text and sharpens focus on the key details.
Single-Item Lists
Standalone lists with just one item disrupt uniformity and suggest formatting errors. Integrate the item into the lead-in phrase.
Example: Instead of a list reading 'Input parameter: user_id', write: 'The input parameter user_id is the user identifier'.
Punctuation in Lists
Maintain consistency:
- Lines starting with a capital letter end with a period.
- Lines starting lowercase end with a semicolon.
For multi-paragraph items, use the first style. This follows technical documentation standards.
Rules for Nested Lists
Nesting simplifies hierarchical structures but demands discipline.
Numbering Levels:
- Level 1: 1, 2, 3
- Level 2: 1.1, 1.2
- Level 3: 1.1.1, 1.1.2
Avoid letters and Roman numerals—they complicate navigation.
Nesting Limit: No more than 5 levels. If needed, split into subsections. Four levels are recommended for optimal readability.
After Unordered Lists: Do not resume numbering. This avoids numbering ambiguity.
Example of a problematic structure:
- Level 1
1.1. Level 2
- Unordered
1.1.1? // Unclear
Key Points
- Use numbered lists only for sequences; unordered lists for sets.
- Lead-in phrase with a unifying term is mandatory—no quantity specified.
- Noun phrases and no repetitions in items.
- Maximum 5 nesting levels; numbering doesn't continue after bullet markers.
- Punctuation: period for capitalized lines, semicolon for lowercase.
Lists boost scannability in technical texts like documentation, guides, and articles. Following these rules minimizes cognitive load for mid/senior developers and technical specialists.
— Editorial Team
No comments yet.