Как сделать оформление статьи более удобным для читателей

В этом документе собраны рекомендации по написанию статьей Базы знаний, их оформлению.

Название статьи

Пишите короткое и понятное название для статьи. Название не должно включать несущественную информацию и много подробностей, но в то же время оно должно дать понять читателю, что предложенный материал решает какую-то конкретную «проблему».

Структура статьи

Последовательность изложения

В статьях следует повествовать:

• от общего к частному;
• от простого к сложному;
• в порядке важности, известности, достоверности, размера, расположения;
• в хронологическом порядке — для исторической справки;
• в тематическом порядке — удобно в иерархических списках;
• в алфавитном порядке, когда другие не подходят.

Заголовки

Используйте заголовки различных уровней, для разбития смысловых блоков.

Заголовки набираются по следующим правилам:

• каждый заголовок занимает отдельную строку;
• не ставится точка в конце;
• перед заголовком одна строка остаётся пустой;
• Заголовки рекомендуется нумеровать для:
• технологических документов;
• документов, имеющих сложную структуру: более трех уровней заголовков, при этом 5 и более заголовков одного уровня.

Абзацы

Разбивайте текст на абзацы (в одном абзаце 4-5 предложений) - так его будет легче воспринимать.

Худшее, что может быть с текстом — это если он вставлен одной сплошной простынёй. Случайный скролл колесом (или неаккуратное касание до планшета) и всё, вы уже потеряли место, где читали.

Разделение текста на абзацы осуществляется набором одной пустой строки. Единичный перевод строки не приводит к созданию нового абзаца, но может быть полезен для упорядочивания текста и удобства просмотра на этапе редактирования.

Списки

Чтобы упорядочить текст относящийся к одной тематике и содержащий, как правило, последовательное перечисление или инструкцию к выполнению используйте списки.

Маркированные списки обычно применяются для перечисления параметров, порядок следования которых не важен (например, список свойств какого-либо продукта).

Нумерованные списки применяются при необходимости перечислить элементы списка в определенном порядке

(например, инструкция по сборке мебели).

Уведомления

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

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

Существует три типа редактируемых блоков уведомлений, которые можно использовать для вывода информации: Информация, Подсказка, Предупреждение

Выделение

Для логического выделения слов в тексте следует использовать полужирное и курсивное начертания шрифта.

Полужирный шрифт

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

Курсив

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

Полужирный курсив

Полужирным курсивом выделяются производные термины, не являющиеся синонимами основного предмета статьи, но также определяемые в её тексте.

Знаки препинания

При расстановке знаков препинания в тексте статей в первую очередь следует руководствоваться действующими правилами русского языка.

Запятая, точка с запятой, двоеточие, точка, многоточие, вопросительный и восклицательный от предшествующего слова пробелом не отделяются, но отделяются одиночным пробелом от последующего слова

Прочие советы

• Используйте предопределенные системой шаблоны.
• Обращайте внимание на то, как оформляют публикации другие пользователи. Почти каждый день для этого публикуется множество примеров.
• Обращайте внимание на отступы. У разных объектов они разные – у заголовков один отступ, у картинки или тега с кодом – другой. Некрасиво, когда в публикации есть лишние переносы строк, а картинки «прилипают» к тексту.
• Пользуйтесь орфографом/типографом. Дефисы, кавычки, многоточия и т.д. – это на ваше усмотрение. Но вот грамматические ошибки мало кому понравятся – исправляйте хотя бы то, что подчёркивает браузер.

Описание области знаний

Эта область для накопления знаний, которые будут полезны всем сотрудникам: например, о порядке оформления заявлений, организации доступа к внутренним ресурсам, порядке получения допусков и пропусков и т.д.

Основные разделы

Добавьте ссылки на ключевые статьи области знаний для удобства поиска и навигации