Существуют различные языки форматирования, чтобы управлять тем, как текст появляется в документации по программному обеспечению. Один из самых важных — отметка. Он обеспечивает простой синтаксис для генерации заголовков, подчеркнутый текст, упорядоченные/неупорядоченные списки и многое другое. Сегодня Markdown является стандартным инструментом для создания технического контента, такого как проекты, найденные в GitHub или других веб-местах.
Markdown — это легкий язык разметки, используемый для добавления форматирования в простые текстовые документы. Созданный в 2004 году Джоном Грубером, его основная цель-позволить людям писать, используя простой для чтения, простой в записи формат простого текста, который можно при желании преобразовать в структурно действительный HTML (или XHTML).
По сути, Markdown позволяет вам создавать форматированный текст (например, заголовки, жирный текст, курсив, списки, ссылки и изображения), используя простой синтаксис, который является ненавязчивым и остается очень читаемым даже в своей необработанной, неспособной форме.
Документация может быть неотъемлемой частью любого проекта разработки. Он предоставляет критическую информацию, в том числе:
- Обеспечивает передачу и сохранение знаний о применении.
- Обеспечивает сотрудничество и устранение неполадок.
- Обеспечивает соблюдение и качество.
- Обеспечивает масштабируемость и улучшения функций.
Простота Маркдауна делает его отличным вариантом для документирования проектов. Имейте в виду, что есть несколько разных ароматов, каждый с особыми сильными сторонами. Очень важно, чтобы ваша организация стандартизировала один аромат.
Общие вариации отметки включают в себя:
- Отметка (оригинал): исходная спецификация.
- Commonmark: Проясняет аспекты исходной спецификации для большей последовательности. Обычно это стандартный вкус.
- GitHub ароматизированная отметка: Добавляет больше функций разметки, включая таблицы, списки задач, ударные и другие компоненты. Используйте это, если вы будете регулярно публиковать в GitHub.
- Ударная дополнительная: Добавляет новые функции, включая сноски. Часто используется с WordPress.
Обязательно изучите возможности каждого инструмента, прежде чем выбрать один для вашей команды.
Лучшие практики
Интеграция Markdown в проекты документации требует не только выбора спецификации версии. Нажмите на этот критический первый шаг, установив стандарты форматирования, которые соответствуют потребностям вашей организации, команды или проекта. Определение руководства по стилю, которое позволяет всем авторам создавать последовательную документацию, предлагает наилучшие шансы на успех.
Рассмотрим следующие лучшие практики для использования Markdown в документации:
Планирование: Планируйте успех, определив, что документация должна (и не должна) покрывать. Определите обязанности, местоположения хранения и вкус наценки.
- Определите аспекты приложения, которые обращается к документации.
- Определите, кто несет ответственность за создание и поддержание документации.
- Укажите место хранения. В идеале документация находится вместе с приложением в репозиториях, таких как Github.
- Укажите поддерживаемый аромат отметки, который должны использовать все авторы.
Структура и организация: Организовать документацию с четкой и логической структурой, которая ведет читателей через необходимые шаги, опираясь на концепции.
- Используйте три или меньше заголовков для определения разделов.
- Включите файл readme.md, чтобы объяснить сферу документации, структуру и цель.
Форматирование: Определите и используйте согласованный формат для всей документации.
- Бюровые списки легко сканировать и улучшить читаемость.
- Используйте пронумерованные шаги для последовательных задач.
- Применить дату и стандарты времени.
- Используйте внутренние ссылки для ссылки на другие части документа.
Рисунок 1: Маркаун отображается слева с предварительным просмотром справа. Обратите внимание на заголовки, ссылки и списки.
Синтаксис: Тщательно управлять примерами кода и команд, чтобы обеспечить ясность. Определите, когда использовать встроенный код в сравнении с блоками кода.
- Используйте встроенные форматы кода для отдельных команд, имен файлов, флагов или других ссылок на код.
- Используйте кодовые блоки для существенных команд или фрагментов.
- Укажите языки программирования при использовании кодовых блоков.
Рисунок 2: Используйте встроенное форматирование кодирования для отдельных команд. Используйте кодовые блоки для больших фрагментов.
Ясность: Используйте простой язык и избегайте идиом. Помните, что многие документационные проекты переведены на несколько языков.
- Записайте аббревиатуры в первый раз, когда вы их используете.
- Избегайте сленговых терминов.
- Добавьте метаданные в верхней части файлов документации, чтобы суммировать контент.
- Полагайтесь на короткие абзацы и предложения, чтобы поддерживать простоту.
- Тщательно проверяйте документацию на наличие орфографических и грамматических ошибок.
- Не чрезмерно используйте курсив, жирным шрифтом, подчеркивание и другие методы подчеркивания информации.
Доступность: Планируйте доступность при написании документации, особенно вокруг URL -адресов и изображений.
- Используйте Alt Text для изображений для поддержки считывателей экрана. Алт текст также помогает с seo.
- Предоставьте описательный текст для URL и изображений.
Рисунок 3: Описательные альтернативные текстовые считыватели Screen Screen Readers и результаты seo.
Последовательность: Последовательное форматирование, словарный запас и организация расширяют возможности полезной документации.
- Разработайте руководство по стилю для всех авторов документации, чтобы следовать.
- Используйте инструменты Linkdown Linting, чтобы поймать ошибки и поддерживать стиль.
- Запросите обратную связь от пользователей о том, как улучшить документацию.
Обслуживание: Обновить документацию, когда приложение версирует.
- Выпекать ресурсы документации (время, деньги и т. Д.) В план обновления версии.
- Убедитесь, что новые разделы соответствуют остальной части документа.
- Создайте новые внутренние ссылки для новых разделов.
Постоянное улучшение: Стремиться к постоянному улучшению документации.
- Запрашивать и интегрировать отзывы пользователей.
- Убедитесь, что организация документации остается логичной между изменениями версий и улучшения функций.
- Тщательно просмотрите документацию, чтобы поймать несоответствия и ошибки.
- Проверьте все внутренние и внешние ссылки, чтобы избежать разбитых ссылок, которые приводят к путанице или разочарованию.
Многие приложения, особенно проекты с открытым исходным кодом, полагаются на целое сообщество для поддержания документации. Руководства по стилю, шаблоны и четкие ожидания имеют решающее значение в этих совместных средах. Признание того, что многие люди будут работать с документацией с течением времени, важно.
Редактировать это божественное
Поиск подходящего редактора является еще одной важной частью использования разметки для документирования ваших проектов. В то время как любой базовый текстовый редактор будет работать, инструмент, способный отобразить предварительный просмотр, очень полезен. Тот, который предлагает лининг или проверку синтаксиса, также поможет.
Многие общие редакторы расширяются и могут быть сделаны для работы с Marckdown. Обязательно проверьте свой существующий набор инструментов, чтобы увидеть, есть ли у вас знакомая утилита Markdown.
- Visual Studio Code: ваши кодеры уже могут использовать этот редактор, что позволяет легко изменять его конфигурацию для Markdown.
- Stackedit: веб-редактор с интегрированным предварительным просмотром и редактированием Windows. Он включает в себя интеграцию с облачным хранилищем, такой как Dropbox и Google Drive.
- Tipora: предлагает отличные возможности предварительного просмотра и расширенные функции.
- Призрачный писатель: редактор, богатый функциями с режимом фокусировки, различные экспортные возможности и параметры предварительного просмотра в прямом эфире.
Потратьте некоторое время на оценку этих приложений перед стандартизацией.
Заворачивать
Все больше и больше ИТ-отделов полагаются на кодовые проекты, от традиционных работ по развитию до инфраструктуры в качестве кода. Обеспечение того, чтобы ваши команды по разработке и администрированию генерировали точную, простую и текущую документацию имеют решающее значение для долгосрочного успеха ИТ-проектов. Markdown — отличный инструмент для удовлетворения этого требования.
Вы выберете Markdown для его простых, но надежных возможностей форматирования, делая работу приложений документации гораздо менее громоздкой. Следуйте вышеупомянутым лучшим практикам, чтобы обеспечить наилучшие шансы на успех.
Trending Stories youtube.com/thenewstack Tech движется быстро, не пропустите эпизод. Подпишитесь на наш канал YouTube, чтобы транслировать все наши подкасты, интервью, демонстрации и многое другое. Группа подпишитесь с эскизом. Дэймон М. Гарн владеет Cogspinner Coaction, LLC, компания по написанию и редактированию IT. Он авторы статей, учебных пособий и лабораторий для сегодняшних лидеров ИТ -индустрии. Он регулярно вносит свой вклад в новый стек, TechTarget и Comptia. Деймон имеет 20 лет … Подробнее от Дэймона М. Гарна
