Как выстроить заголовки и оглавление инструкции
Сделайте длинный Markdown-документ удобным для просмотра по заголовкам и проверьте оглавление после публикации.
На третьем экране инструкции читатель ищет, где заказать доступ. Автор выделил нужный текст жирным, но в оглавлении его не видно. Другой раздел начинается с заголовка третьего уровня сразу после названия страницы. Для человека, который пролистывает документ по заголовкам, такая структура может выглядеть неполной. Уровни Markdown стоит выбирать по вложенности, а пригодность оглавления проверять на готовой странице.
Начните с вопросов читателя
Представим инструкцию «Как провести встречу клуба». Выпишите четыре вопроса. Что подготовить? Как начать? Как завершить? Где сохранить материалы? Эти вопросы и дадут четыре самостоятельных раздела. Если в подготовке есть две связанные задачи, например приглашения и оборудование, они могут стать подразделами. Если задача занимает всего две строки, достаточно абзаца или пункта списка. Избыточные подзаголовки заставляют читателя переходить между маленькими фрагментами, которые легче понять вместе.
Сверьте формулировки с действиями. «Материалы» может означать презентацию, список участников или итоги. «Сохранить материалы встречи» сообщает, где искать следующий шаг. Для справочника уместна формулировка вопросом, например «Где лежит запись встречи?». Выберите тот вариант, который лучше помогает читателю узнать свой запрос. Внутри одного документа придерживайтесь понятного порядка, но не жертвуйте ясностью ради одинаковых частей речи в заголовках.
Свяжите уровни с положением в документе
В исходнике Markdown число решёток перед пробелом определяет уровень ATX-заголовка. Главный заголовок описывает весь документ. Заголовки второго уровня обозначают основные разделы, а третий уровень открывает их подразделы. Возврат к более высокому уровню завершает вложенную часть. Не перескакивайте вниз с первого сразу на третий ради меньшего шрифта. Если документ уже получает название из шаблона сайта, сначала проверьте итоговый HTML. Шаблон может выводить собственный главный заголовок, и тогда тело статьи нужно начинать с уровня разделов.
# Как провести встречу клуба
## Подготовить встречу
### Разослать приглашения
### Проверить проектор
## Начать встречу
## Сохранить материалы встречиПосмотрите на пример без основного текста. Заголовок «Проверить проектор» явно относится к подготовке. «Начать встречу» уже находится рядом с подготовкой, поэтому его уровень снова второй. Если внутри начала появится шаг «Показать повестку», решить, нужен ли новый заголовок, можно по содержанию. Для одного короткого указания лучше оставить пункт списка, а не ещё один пункт оглавления.
Уберите признаки, которые только выглядят как заголовки
Полужирная строка может помогать глазами, но в HTML она обычно остаётся частью абзаца. Она не создаёт заголовок, по которому можно перемещаться средствами навигации или вспомогательной технологии. Это нормально для подписи «Пример» перед одним блоком. Если текст объединяет несколько параграфов в самостоятельный раздел, лучше дать ему настоящий заголовок.
Обратная ошибка — использовать заголовок ради большого шрифта внутри предупреждения. Из-за этого в оглавлении появляется пункт, не соответствующий отдельной теме. Перенесите важное предложение в начало абзаца и выделите ключевые слова. Если платформа позволяет настраивать оформление, задайте подходящий стиль. Тогда структура документа будет передавать смысл независимо от внешнего вида.
Проверьте переходы после сборки
Многие редакторы и генераторы строят оглавление из заголовков. Преобразование текста в идентификатор ссылки зависит от среды. Не переносите вручную угаданный адрес фрагмента из одной системы в другую. Откройте опубликованную версию, нажмите пункт оглавления и скопируйте реальный адрес из браузера. Особенно внимательно проверьте заголовки с одинаковым текстом и знаками препинания. Два раздела «Проверка» удобнее назвать «Проверить оборудование» и «Проверить комплект материалов». Так различие будет понятно и при чтении оглавления без остальной страницы.
Если на инструкцию уже есть внешние ссылки, переименование заголовка может изменить адрес фрагмента. При новой редакции проверьте переходы из тех мест, где вы управляете ссылками. Сохранить прежний адрес можно только средствами конкретной платформы. Не добавляйте произвольный HTML-якорь, если площадка очищает HTML или не поддерживает этот подход. Иногда проще переименовать раздел, обновить управляемые ссылки и отметить смену адреса в заметке о выпуске.
Используйте оглавление как контрольный список
Откройте список заголовков и попробуйте выбрать, куда пойдёте за ответом на исходные четыре вопроса. Пройдите переходы с клавиатуры, если оглавление состоит из ссылок. Убедитесь, что после перехода видна нужная часть документа и что фокус не теряется при дальнейшей навигации. Затем прочитайте первый абзац каждого раздела. Он должен отвечать на вопрос заголовка или ясно объяснять следующий шаг. Если первые предложения повторяют только название, используйте это место для результата или условий.
Результат можно считать готовым, когда смысл структуры виден из одного списка, каждый подраздел относится к своему родителю, а все ссылки оглавления ведут к уникальным местам. Для короткой заметки достаточно двух или трёх разделов. Дополнительное оглавление имеет смысл, когда оно действительно сокращает поиск.
Различайте краткое и полное оглавление
Если разделов много, начните с оглавления только верхнего уровня. Для раздела с длинной процедурой добавьте внутри короткие ориентиры. Сверьте их с реальными шагами. Когда человек открывает страницу с телефона, полный список подразделов может занять весь первый экран. Короткий маршрут оставляет место для вступления, а подробные ориентиры встречаются там, где они нужны. Проверяйте названия после такой перестройки, потому что заголовок, понятный внутри раздела, иногда выглядит двусмысленным в общем списке.