Как Vuepress помог моей документации

Всего пару часов и сайт готов

Как сказал мне однажды один учитель: «Программное обеспечение живет и умирает благодаря документации». По правде говоря, даже самое интуитивно понятное программное обеспечение нуждается в каком-то руководстве, и при создании пакетов для Packagist и NPM вы также ожидаете, по крайней мере, несколько строк инструкций.

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

models:
  User:
    name: string
    email: string
    password: string
    posts: hasMany
  Post:
    title: string
    body: text
    user: belongsTo

Проблема в том, что вам нужно сделать что-то, что вы не знаете, как это сделать. Например, используйте UUID в качестве первичного ключа или используйте сводную модель. Именно тогда вам нужно прочитать документацию, и именно тогда конечный пользователь полюбит ваше программное обеспечение или удалит его, чтобы найти что-то менее сложное.

Из Гитбуков…

Gitbooks стал моим первым выбором для документации: очень интуитивно понятный, в основном графический, поддерживает своего рода «автосохраненные черновики» и несколько черновиков, все без строки кода, push/pull или знания, что такое git. Он легко интегрировался в свежий репозиторий, чтобы хранить все.

Отличительной особенностью Gitbooks является не то, что есть, а то, как он использует ваш браузер, чтобы помочь вам писать в Microsoft Word, как в лучшие дни. У вас есть много инструментов в вашем распоряжении, и вам не нужно ничего кодировать, так что вы чувствуете себя как дома.

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

https://johndoecussings.gitbook.com/docs

Кроме того, в самой теме мало контроля, кроме бесплатной, что достаточно для тех, кто ищет что-то попроще, но не для меня.

Затем я наткнулся на Vuepress, тот же движок сайта, который используют разработчики Vue для своей документации. И теперь документация работает на этом.

…в Vuepress

Итак, как прошла смена? Что ж, Vuepress предлагает гибкость и некоторые функции, недоступные в Gitbooks, по крайней мере, не на первый взгляд, например выделение строкового кода. Хотя есть функции, которые не предлагает ванильная тема Vuepress, есть полный список плагинов, которые делают ее более полной.

Конечно, изменения не обошлись без некоторых проблем, но тем не менее, это заняло менее часа с поиском и заменой REGEX и изменением каталогов.

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

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

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

Одна хорошая функция, которая предлагает Vuepress из коробки, — это домашняя страница «всплеск». Он был создан менее чем за минуту.

Единственная проблема, с которой Vuepress может столкнуться для многих людей, заключается в том, что это не графический инструмент, а очень многословный. Люди, не обладающие знаниями в области кодирования или не умеющие легко блевать кодом вместо редактора WYSIWYG, вообще не будут использовать Vuepress. движок не предлагает ни графического интерфейса, ни инструментов для отправки документации через Интернет — в случае с Larawiz она была загружена на Github Pages — так что вы привязаны к тому, что у вас есть, будучи что ваша любимая IDE или Notepad++.

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

Vuepress сначала требуется некоторая настройка, особенно на боковой панели, в то время как Gitbooks не угадает и не угадает большинство вещей, чтобы ваша функция документации была полной. Если вы не хотите вставлять некоторые строки в файл YAML (как я решил вместо простого JSON) и редактировать файлы vanilla Markdown без графического интерфейса, тогда Vuepress может быть не для вас, но опять же, кто те люди, которые создаете документацию и не знакомы с git, Markdown и Javascript?

Итак, чем хорош Vuepress?

Возвращаясь к документации Larawiz, да, это хорошо. Благодаря гибкости темы она уже лучше, чем Gitbooks, но мне будет не хватать более четкого графического интерфейса, который предлагал создавать текстовые блоки, такие как заголовки, подсказки и некоторые расширенные синтаксис, одним щелчком мыши. Я буквально скучаю по нажатию CTRL + /, чтобы открыть меню с различными блоками текста, которые я мог бы добавить, что заставляет меня сосредоточиться на том, что писать, а не на подробном описании моего пути в документацию.

К счастью, Larawiz не использует продвинутые вещи, и если ему нужно что-то вне Vuepress, вы можете использовать сторонний плагин или сделать это самостоятельно.

Я, вероятно, не буду оглядываться назад, если не выйдет что-то лучше, чем Vuepress. Будем надеяться, что следующая вещь, которую выпустит команда Vuepress, — это графический интерфейс и автоматическая публикация на таких сайтах, как страницы Github, страницы Gitlab, кто знает. Это означает меньше времени на настройку и загрузку плагинов и больше времени на фактическое использование Vuepress для исправления того, что должно было быть исправлено.

О документации, вы можете попробовать и попробовать Larawiz самостоятельно.