Недавно я в очередной раз прочитал на Хабре, что списки — это один из признаков текста, созданного нейросетью. Значит меня можно считать «нейросетью» устаревшей модели, выпущенной ещё в 70-х годах XX века. Я начал составлять списки в детстве, почти сразу, как только научился писать.

Я очень люблю списки: они позволяют легко и в то же время наглядно структурировать информацию. По эффективности списки находятся где-то между текстом, в котором объекты перечисляются в строке через запятую, и таблицей, которая по сути является двухмерным списком. Взгляд читателя легко скользит по номерам или маркерам списка. Можно быстро оценить количество строк, понять их последовательность и структуру, перейти к нужной строке.

В этой статье я хочу поделиться с вами своими правилам оформления списков. Эти правила я всегда стараюсь соблюдать в своих текстах, когда нет иных внешних требований.

1. Нумеровать или нет

Нумерованные списки я использую обычно в том случае, когда важен порядок следования строк. Например, когда в списке перечисляются действия, которые одно за другим должен совершить читатель. Ненумерованные — для простых перечислений каких-то объектов.

Кстати, на номер можно легко сослаться. Например: «В шаге 438 используйте результаты шага 2». Если что, это сарказм. На всякий случай сразу добавлю: лучше минимизировать количество строк в списке. Тут главное без фанатизма: списки из сотен строк, конечно, бывают. Но лучше не издеваться подобными изощрёнными способами над читателем.

Update: Мой хороший друг и соратник добавляет, что «нумерованными списками удобно формулировать какую-либо доктрину массового применения: 10 заповедей, 7 смертных грехов, 5 признаков империализма...» Да и разделы в статьях (в том числе и в этой статье) — это тоже нумерованный список.

2. Титульная фраза задаёт тон

Я всегда пишу перед списками титульную фразу. Она помогает читателю понять, что именно перечисляется в списке. Примеры титульных фраз:

• Чтобы установить систему, выполните следующие действия: …

• Входные параметры метода test: …

• Вася, для новогоднего стола тебе нужно закупить следующие продукты: ...

Правила формирования титульной фразы такие:

• Фраза содержит термин, который объединяет объекты перечисления: «действия», «параметры», «продукты».

• Объединяющий термин желательно располагать ближе к концу фразы. Но не обязательно.

• Если объединяющий термин никак не подобрать, то можно воспользоваться универсальными словами: «элемент», «действие», «часть» и другими. Если и они не подходят, то тут впору задуматься: а действительно ли в списке перечисляются однородные объекты.

• Фраза не должна содержать указание на количество строк списка. Например: «Система передаёт 5 параметров:...». Когда параметров вдруг станет 6, очень легко забыть поменять цифру в титульной фразе. Да и вообще, в большинстве случаев количество параметров вообще не важно.

3. Именительный падеж — всему голова

Я всегда стараюсь все элементы списка перечислять в именительном падеже. Ну и, конечно, все строки списка должны быть согласованы друг с другом. Обычно над списками достаточно легко провести такую «нормализацию». Видим, что «Процесс продажи состоит из: заготовки, подготовки, отгрузки, ...» и лёгким движением руки превращаем всё это в симпатичные шорты: «Процесс продажи состоит из следующих этапов: заготовка, подготовка, отгрузка, ...»

4. Попугаям здесь не место

Иногда в технической документации встречаются списки, строки которых начинаются с одного и того же слова. Например, «библиотека такая-то», «библиотека сякая-то» и так далее — ещё куча всяких библиотек.

Как будто с попугаем разговариваешь. А всего-то нужно: включить повторяющееся слово в титульную фразу. Например: «Установите следующие библиотеки». А дальше уже в списке строки: «такая-то» и «сякая-то».

5. Строкам грустно в одиночестве

Меня всегда удивляют списки, состоящие из грустной одинокой строки. Обычно они появляются в текстах и документации, когда есть несколько однотипных разделов. Например, в документе описываются какие-то API-методы. Для каждого метода есть список входных параметров. У одного из методов параметр всего один. В этом случае у автора есть большой соблазн добавить список из одной строки. Ну просто так, по аналогии, для единообразия.

Для читателя такие недосписки выглядят странно. Может возникнуть даже мысль, что недостающие строки потерялись где-то при форматировании или автор просто забыл их дописать. Я обычно в таких случаях просто присоединяю название параметра к вводной фразе списка. Например: «Входной параметр: user_id — идентификатор пользователя».

6. Пунктуация пунктов

В статье «Мои простые правила хорошего текста: личное руководство по стилю» я уже приводил два главных правила пунктуации в списках:

• Если строка списка начинается с прописной буквы, то в конце я ставлю точку.

• Если строка списка начинается со строчной буквы, то в конце я ставлю точку с запятой.

Если в строке списка должно быть несколько предложений, то это всегда первый вариант.

7. Вложенность вложенности

Иногда в тексте приходится делать вложенные друг в друга списки. Тут у меня тоже постепенно выработались свои правила:

Правило 1. Для строк вложенных нумерованных списков я добавляю новые номера через точку.

Система такая:

• Первый уровень: 1, 2, 3, …

• Второй уровень: 1.1, 1.2, 1.3, …

• Третий уровень: 1.1.1, 1.1.2, 1.1.3, ...

Некоторые программы для вложенных нумерованных списков на разных уровнях по умолчанию используют буквы и римские цифры. Мне не нравятся эти форматы. Буквы не дают читателю чёткого понимания, в каком именно месте списка он находится. Про римские цифры вообще ничего не хочется писать — упрощению восприятия текста они точно не способствуют.

Правило 2. Уровень вложенности — не больше 5.

В некоторых документах встречаются такие монструозные списки, в которых вложенность просто зашкаливает. Например, встречаются строки с номерами «4.5.23.14.1.2.3». Не верите? А я такие видел! До сих пор вспоминаю и всем рассказываю.

Обычно такие монструозные списки появляются, когда автор описывает какой-то сложный алгоритм или процесс со множеством ответвлений. Я для себя установил предел: 5 уровней. Если у меня появляется необходимость добавить шестой уровень, то я сразу автоматически начинаю мероприятия по разбиению этого чудища на отдельные разделы: каждой голове отдельная глава.

Если честно, я уже всерьёз подумываю уменьшить свой лимит вложенности до 4.

Правило 3. После ненумерованных списков нумерация не возобновляется.

Представьте себе такой список: сначала идут вложенные нумерованные списки. Потом на очередном уровне вложенности появляется ненумерованный список (простое перечисление). А потом у автора вдруг возникает идея добавить очередной нумерованный уровень. Но нельзя! Хотя бы потому что будет неясно, как именно выполнять нумерацию в этом списке:

• Первый уровень: 1, 2, 3, …

• Второй уровень: 1.1, 1.2, 1.3, …

• Третий уровень — ненумерованный список.

• Четвёртый уровень: 1.1.1? Или 1.1.1.1?

Можно, конечно, воспользоваться буквами. Но что тогда делать со следующими уровнями? В общем, я всегда соблюдаю правило: если на каком-то уровне вложенности появился ненумерованный список, то дальше вложенных нумерованных списков уже не будет.

Списки — это один из самых удобных и распространённых инструментов структурирования информации в любом тексте: будь то руководство пользователя, справочник или статья. Да и в художественных произведениях они нередко встречаются. Ещё списки помогают обдумывать какие-то идеи и делать заметки. А правильное и красивое оформление любого списка помогает сделать его ещё доступнее и удобнее для читателей.