VuePress: документация стала проще

Когда дело доходит до любого проекта, требующего взаимодействия с пользователем (например, с конечными пользователями, сопровождающими и т. д.), есть один критический фактор, определяющий разницу между успехом и неудачей: хорошая документация. Это справедливо независимо от того, насколько мал или велик ваш проект. В конце концов, помимо индивидуальной поддержки вашего проекта, документация является первой линией защиты для пользователей, пытающихся решить проблему. И, нравится вам это или нет, вы никогда не услышите от пользователей, которые сдаются после того, как не могут решить свою проблему из-за неадекватной документации.

Проблемы создания хорошей документации

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

1. Документация часто устаревает.
   Хотя отсутствие документации для проекта может быть разочаровывающим опытом, возможно, хуже иметь устаревшую документацию. В конце концов, цель наличия документации — предоставить пользователям официальный свод знаний, на который они могут положиться. Когда он устаревает, пользователи тратят свое время и в конечном итоге теряют доверие к вашему продукту.
   
   Основная причина того, что документация устаревает, заключается в том, что сопровождение документации осуществляется отдельно от изменений кода . Без значительных затрат времени и энергии это может быть трудно решить, потому что:
   
   1. Документация обычно находится в стороннем сервисе, таком как Confluence или Wiki.
   2. Разработчики обычно больше заинтересованы в написании кода, чем в документации.
2. Пользователи не могут легко оставлять отзывы.
   Независимо от того, насколько хороша, по вашему мнению, ваша документация, она в конечном счете бессмысленна без тестирования ее с реальными пользователями, которые могут предоставить обратную связь. Как упоминалось ранее, распространенная предвзятость при оценке эффективности таких вещей, как документация, заключается в том, что не учитываются пользователи, которые не смогли решить свои проблемы и сдались. Поскольку ни одна команда никогда не сможет учесть каждый сценарий того, как пользователи могут использовать ваш продукт, у пользователей должен быть простой и надежный способ оставить отзыв.
3. Документация часто пишется опытными пользователями для опытных пользователей.
   Недостаток использования стандартных инструментов, таких как вики или файлы README, заключается в том, что они часто обслуживают только определенный набор пользователей, у которых часто уже есть знания о библиотеке и/или технологическом стеке. В результате им достаточно просто ориентироваться в пространстве и находить то, что им нужно. Однако новым пользователям не хватает этих предварительных знаний, и поэтому для их вовлечения часто требуется гораздо более захватывающий опыт.
   
   Примеры этого включают:
   
   • Хорошо разработанный веб-сайт,
   • Возможность поиска,
   • Управляемая боковая навигация,
   • Легко идентифицируемая метаинформация (например, дата последнего обновления),
   • Иммерсивный контент, выходящий за пределы стены текста, который трудно понять.
4. Плохая инфраструктура, затрудняющая ведение документации.
   Как будто написание хорошей документации, понятной пользователям, недостаточно сложно, легкость, с которой разработчик может писать и/или поддерживать документацию, имеет решающее значение для ее долгосрочной жизнеспособности. Таким образом, с каждым дополнительным барьером, с которым приходится сталкиваться разработчикам при написании и/или сопровождении документации, возрастает вероятность того, что в конечном итоге она потерпит неудачу. В результате крайне важно, чтобы опыт создания и обслуживания любой документации был как можно более плавным и привлекательным.

Если бы только существовал инструмент, который мог бы сделать все это за нас…

Введите VuePress

Когда вы впервые слышите о VuePress, может возникнуть соблазн предположить, что это объединение Vue.js и WordPress. Вместо этого вы должны думать о VuePress как о:

Vue.js + печатный станок

Потому что, когда все сказано и сделано, VuePress — это генератор статических сайтов!

Некоторые из вас могут подумать: «Подождите. Еще один генератор статических сайтов? Подумаешь?"

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

Почему VuePress так эффективен для создания документации?

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

• Создавайте красивые сайты документации,
• Поставляется с готовыми функциями, необходимыми для всех сайтов документации,
• Оптимизируйте процесс разработки, чтобы сделать его таким же простым, как обновление файла Markdown.

VuePress может сосуществовать с вашей существующей кодовой базой

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

Поскольку это генератор статического сайта, это означает, что он может находиться в том же репозитории, что и ваш код.

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

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

Тема по умолчанию поставляется со стандартной конфигурацией

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

• Написание контента выполняется в основном с помощью Markdown.
  Это означает, что вы можете использовать имеющиеся у вас знания о синтаксисе Markdown для оформления и форматирования текста.

• Подсветка синтаксиса кода.
  Если бы вы создавали сайт самостоятельно, вам пришлось бы бороться с библиотеками цветовой подсветки синтаксиса. Но вам повезло, потому что вы можете добавлять блоки кода в VuePress так просто, поскольку все готово к работе без настройки.

• Передняя часть для определения метаданных на уровне страницы.
  Даже если вы создаете файл Markdown, вы можете использовать вводную часть (например, YAML, JSON или TOML), чтобы определить метаданные для своей страницы, чтобы упростить управление вашим контентом!

 --- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---

• Пользовательские контейнеры Markdown.
  Если вы не знали, в Markdown есть расширения для добавления еще более полезных ярлыков для создания красивых компонентов пользовательского интерфейса, таких как пользовательские контейнеры. И поскольку они так полезны в документации, VuePress уже настроил их, чтобы вы могли использовать их прямо из коробки:

Встроенная функция поиска

Давайте смотреть правде в глаза. Независимо от того, сколько времени мы тратим на написание отличной документации, в конечном итоге она окажется бесполезной, если пользователи не смогут ее найти. Обычно есть два подхода к этому:

1. Подождите, пока роботы поисковых систем будут медленно сканировать ваш сайт, в надежде, что однажды ваши пользователи смогут найти нужную страницу на вашем сайте. Не отличное решение.
2. Создайте свою собственную функцию поиска, но это может быть сложно реализовать для статических сайтов, поскольку на стороне сервера не выполняется код для создания поисковых индексов и выполнения поиска. Не говоря уже о том, что это отнимает время на разработку у самого продукта. Так что это тоже не здорово.

К счастью для нас, VuePress снова здесь, чтобы спасти положение!

VuePress поставляется со встроенной функцией поиска, которая создает собственную «поисковую систему» ​​— вы правильно прочитали. Без какой-либо дополнительной настройки или настройки базы данных VuePress настроен на очистку всех ваших документов для создания простой поисковой системы, которая предоставит пользователю все ваши h1 и h2.

Сейчас некоторые из вас могут подумать,

«Что, если мне нужно что-то, что обеспечит индексацию более низкого уровня для поиска?»

Что ж, VuePress поможет вам и в этом, потому что он разработан для простой интеграции с Algolia DocSearch, который может предоставить вам эту функциональность бесплатно, если вы соответствуете их требованиям:

Навигация по боковой панели так же проста, как включение или выключение функции

Любой, кто когда-либо отвечал за управление контентом, знает, насколько сложно создать боковую панель с вложенными элементами, а затем отслеживать, в какой позиции находится читатель при прокрутке вниз. Итак, зачем тратить время на это, когда вы могли бы писать более качественные документы? С VuePress боковая панель так же проста, как переключение на переднюю часть страницы:

Автоматическое создание важных метаданных, которые обычно упускают из виду

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

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

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

Это не становится намного проще, чем это для ваших пользователей.

Развертывание на любом статическом хостинге

Поскольку VuePress по своей сути является генератором статических сайтов, это означает, что вы можете развернуть его на любой популярной платформе хостинга, например:

• Нетлайф
• Страницы GitHub
• Страницы GitLab
• Героку
• Сейчас

Все, что вам нужно сделать, чтобы создать сайт, это запустить vuepress build {{ docsDir }} , где находится ваш каталог, и у вас будет все необходимое для его развертывания в Интернете!

Примечание . Для получения более подробных руководств о том, как это сделать, ознакомьтесь с официальными руководствами по развертыванию для VuePress.

Использование Vue внутри вашего файла Markdown

Знаю, знаю. Мы можем использовать Vue.js в нашей уценке?! Да, вы правильно прочитали! Хотя это технически необязательно, это, вероятно, один из самых захватывающих аспектов VuePress, поскольку он позволяет вам улучшать ваш контент Markdown, как никогда раньше.

Определяйте повторяющиеся данные в одном месте и обновляйте их везде с помощью интерполяции

В приведенном ниже примере вы увидите краткий пример того, как вы можете использовать локальные переменные (например, те, которые определены во вступительной части), а также глобально определенные (например, название сайта):

 --- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!

Используйте компоненты Vue в Markdown

Я дам вам немного времени, чтобы собраться после прочтения этого, но да, живые компоненты Vue с полным экземпляром Vue могут быть вашими, если хотите! Для настройки потребуется немного больше работы, но этого и следовало ожидать, поскольку вы создаете пользовательский контент, который будет работать в вашей документации.

Вот краткий пример того, как компонент Counter будет выглядеть в файле Markdown:

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

Следующие шаги

Если вы хотите создать красивый сайт документации, чтобы ваши пользователи могли узнать, как использовать ваш продукт, это не будет намного проще, чем VuePress. И хотя может быть легко предположить, что VuePress следует использовать только в проектах, использующих Vue.js, это не так уж далеко от истины. Вот лишь несколько примеров различных типов проектов, использующих VuePress для своих сайтов документации:

• Создание CMS
• UmiJS (который создан для React)
• openHAB
• павлин

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

Дополнительные ресурсы

Есть много интересных вещей, которые я не рассмотрел в этой статье (например, создание тем, ведение блога и т. д.), но если вы хотите узнать больше, ознакомьтесь со следующими ресурсами:

• Официальные документы VuePress
• Кураторский список ресурсов, связанных с VuePress
• Галерея VuePress
• Шаблон блога VuePress