Zasady strukturyzowania list w dokumentacji technicznej
Listy skutecznie strukturyzują informacje pomiędzy zwykłym wyliczeniem a tabelami. Stosuj listy numerowane do czynności sekwencyjnych, gdzie kolejność ma znaczenie: kroki instalacji, algorytmy. Listy nienumerowane — do wyliczeń elementów bez ścisłej kolejności: parametry, komponenty.
Ogranicz długość list rozsądnymi granicami. Listy z setkami wierszy utrudniają odczyt — podziel je na podsekcje lub tabele.
Wprowadzająca fraza jako punkt orientacyjny
Przed każdą listą zawsze używaj wprowadzającej frazy określającej wyliczenie. Nadaje ona kontekst i spaja elementy.
Przykłady wprowadzających fraz:
- Wykonaj następujące czynności w celu zainicjowania:
- Główne parametry funkcji:
- Wymagane komponenty systemu:
Zasady tworzenia:
- Umieść łączący termin (czynności, parametry, etapy) bliżej końca.
- Unikaj wskazywania liczby elementów — może się zdezaktualizować przy zmianach.
- Jeśli termin nie pasuje, użyj uniwersalnych: element, część, krok.
To zapewnia spójność i ułatwia skanowanie tekstu.
Mianownik dla spójności
Elementy listy zapisuj w mianowniku. To ujednolica strukturę i poprawia czytelność. Przykład przekształcenia:
Nieprawidłowo: Proces składa się z: przygotowania surowca, przygotowania, wysyłki.
Prawidłowo: Proces składa się z następujących etapów: przygotowanie surowca, przygotowanie, wysyłka.
Wszystkie wiersze powinny być gramatycznie spójne, bez mieszania przypadków.
Unikaj powtórzeń w elementach
Powtarzające się słowa na początku wierszy listy tworzą efekt „papugi". Przenieś wspólne słowo do wprowadzającej frazy.
Przykład:
Nieprawidłowo:
- Biblioteka A
- Biblioteka B
- Biblioteka C
Prawidłowo: Zainstaluj następujące biblioteki:
- A
- B
- C
To skraca tekst i zwiększa skupienie na kluczowych informacjach.
Listy z jednym elementem
Samotne listy z jednym wierszem naruszają jednolitość i budzą podejrzenia o błędy formatowania. Wpleć element w wprowadzającą frazę.
Przykład: Zamiast listy „Parametr wejściowy: user_id” napisz: „Parametr wejściowy user_id to identyfikator użytkownika”.
Interpunkcja w listach
Zachowaj konsekwencję:
- Wiersz zaczynający się wielką literą kończy się kropką.
- Wiersz małą literą — średnikiem.
Dla wieloabzacikowych wierszy stosuj pierwszą opcję. To odpowiada standardom dokumentacji technicznej.
Zasady list zagnieżdżonych
Zagnieżdżenie ułatwia struktury hierarchiczne, ale wymaga dyscypliny.
Numeracja poziomów:
- Poziom 1: 1, 2, 3
- Poziom 2: 1.1, 1.2
- Poziom 3: 1.1.1, 1.1.2
Unikaj liter i rzymskich cyfr — komplikują nawigację.
Limit zagnieżdżenia: Nie więcej niż 5 poziomów. W razie potrzeby podziel na podsekcje. Zalecane 4 poziomy dla optymalnego odbioru.
Po liście nienumerowanym: Nie wznawiaj numeracji. To zapobiega niejednoznaczności.
Przykład problematycznej struktury:
- Poziom 1
1.1. Poziom 2
- Nienumerowany
1.1.1? // Niejasne
Co ważne
- Używaj list numerowanych tylko do sekwencji, nienumerowanych — do zbiorów.
- Wprowadzająca fraza z łączącym terminem obowiązkowa, bez podawania liczby.
- Mianownik i brak powtórzeń w elementach.
- Maksymalnie 5 poziomów zagnieżdżenia, po znacznikach numeracja nie jest kontynuowana.
- Interpunkcja: kropka dla wielkich liter, średnik dla małych.
Listy zwiększają skanowalność tekstów technicznych: dokumentacji, instrukcji, artykułów. Przestrzeganie zasad minimalizuje obciążenie poznawcze dla programistów średniego/senior i specjalistów technicznych.
— Editorial Team
Brak komentarzy.