# Pravidla strukturování seznamů v technické dokumentaci
Seznamy efektivně strukturovají informace mezi lineárním výčtem a tabulkami. Číslované používejte pro sekvenční akce, kde je důležité pořadí: kroky instalace, algoritmy. Nečíslované – pro výčty objektů bez přísného pořadí: parametry, komponenty.
Omezte délku seznamů rozumnými limity. Seznamy se stovkami řádků ztěžují vnímání – rozdělte na podsekce nebo tabulky.
Titulní fráze jako orientační bod
Před seznamem vždy použijte úvodní frázi, která definuje výčet. Ta stanoví kontext a spojuje prvky.
Příklady titulních frází:
- Proveďte následující akce pro inicializaci:
- Hlavní parametry funkce:
- Potřebné komponenty systému:
Pravidla tvorby:
- Zahrňte spojující termín (akce, parametry, etapy) blíže ke konci.
- Vyhněte se uvedení počtu prvků – může se zastarat při změnách.
- Pokud termín nevyhovuje, použijte univerzální: prvek, část, krok.
To zajišťuje jednotnost a usnadňuje skenování textu.
Nominativ pro shodu
Prvky seznamu uveďte v nominativu. To normalizuje strukturu a zlepšuje čitelnost. Příklad transformace:
Nesprávně: Proces se skládá z: přípravku, přípravy, odeslání.
Správně: Proces se skládá z následujících etap: přípravek, příprava, odeslání.
Všechny řádky musí být gramaticky shodné, bez míchání pádů.
Vyhněte se opakováním v prvcích
Opakující se slova na začátku řádků seznamu vytvářejí efekt papoušků. Přeneste společné slovo do titulní fráze.
Příklad:
Nesprávně:
- Knihovna A
- Knihovna B
- Knihovna C
Správně: Nainstalujte následující knihovny:
- A
- B
- C
To zkracuje text a zvyšuje fokus na klíčové informace.
Seznamy s jedním prvkem
Osamělé seznamy z jedné řádky narušují jednotnost a vyvolávají podezření na chyby formátování. Integrujte prvek do titulní fráze.
Příklad: Místo seznamu „Vstupní parametr: user_id“ napište: „Vstupní parametr user_id – identifikátor uživatele“.
Interpunkce v seznamech
Dodržujte konzistenci:
- Řádek s velkým písmenem končí tečkou.
- Řádek s malým písmenem – středníkem.
Pro víceodstavcové řádky použijte první variantu. To odpovídá standardům technické dokumentace.
Pravidla pro vnořené seznamy
Vnořenost zjednodušuje hierarchické struktury, ale vyžaduje disciplínu.
Číslování úrovní:
- Úroveň 1: 1, 2, 3
- Úroveň 2: 1.1, 1.2
- Úroveň 3: 1.1.1, 1.1.2
Vyhněte se písmenům a římským číslicím – ztěžují navigaci.
Limit vnořenosti: Ne více než 5 úrovní. Při potřebě rozdělte na podsekce. Doporučeno 4 úrovně pro optimální vnímání.
Po nečíslovaném seznamu: Neobnovujte číslování. To zabraňuje nejednoznačnosti číslování.
Příklad problematické struktury:
- Úroveň 1
1.1. Úroveň 2
- Nečíslovaný
1.1.1? // Nejasné
Co je důležité
- Používejte číslované seznamy jen pro sekvence, nečíslované pro sady.
- Titulní fráze se spojujícím termínem je povinná, bez uvedení počtu.
- Nominativ a absence opakování v prvcích.
- Maximálně 5 úrovní vnořenosti, po značkách číslování ne pokračuje.
- Interpunkce: tečka pro velká písmena, středník pro malá.
Seznamy zvyšují skenovatelnost technických textů: dokumentace, příručky, články. Dodržování pravidel minimalizuje kognitivní zátěž pro middle/senior vývojáře a technické specialisty.
— Editorial Team
Zatím žádné komentáře.