Комментарии 17
Я зашёл почитать свет и умный текст, но задачу, которую вы описываете, её давным-давно в большинстве проектов решили. Да, документация хранится в том же гите и оттуда же генерируется. Насчёт накладывания стилей это вопрос отдельный, но в целом, пандок и вперёд.
А вот проблему, с которой я борюсь, кажется, никто пока системно не решил. Это проблема гниющей документации.
Вот, допустим, у нас где-то в документации написан пример:
Установите пакет foobar и запустите последовательность команд
foobar foo GUID foobar bar UUID
foobar fooвыведет UUID для передачи вfoobar bar.
GUID можно узнать в свойствах foo в self-serving сайте (main -> Foos -> Details).
Дальше:
- UI дизайнер перенёс GUID из Detail в Info
- PM волевым решением переименовал Foos в
Flocked Outstanding Outers. - Программист поменял вывод
foobar foo, которая теперь не показывает UUID по-умолчанию, а вместо этого требует вызватьfoobar foo --all. - Другой программист поменял параметры для bar и теперь оно требует передавать одновременно не только UUID, но и GUID.
- Билд-инженер разделил пакет foobar на foobar-server, foobar-cli, и утилита
foobarуехала в foobar-cli.
Итог? Сгнившая документация.
Я попробовал приделать CI, чтобы он выполнял команды из примеров. Но там слишком много human readable получилось, и весь мой CI в итоге проверял 1 пункт из 10 в инструкции (на которой я пробовал этот подход).
Сейчас я пытаюсь придумать как бы мне из bdd-фреймворка сделать и документацию, и тесты, но пока туговата каменная чаша...
Вы можете вынести примеры кода в отдельные файлы и тестировать их так же, как тестировали бы код. Само не обновится, но хотя бы вы сразу узнаете об ошибке, потому что тесты свалятся.
Ещё вы можете генерировать часть документации из кода. Кайф легковесных разметок вроде MD или rST в том, что их легко автогенерить.
Именно так я и сделал. Три дня возни по изготовлению микрофреймворка по вызову этих файлов из CI'я, их инклюдов в доки, подготовки человекочитаемых имён переменных и т.д., и на выходе я тестировал одну-единственную шелловую команду тривиального содержимого. Потому что в инструкции на 10 пунктов 9 было в немашиночитаемом виде (типа, "закажите новый сервер на замену", "выключите старый умерший сервер").
Т.е. теория у меня именно такая была, практика показала, что не работает. Надо что-то дальше думать.
Ещё я обнаружил, что сам этот фреймворк добавил хрупкости, потому что в структуре CI образовались очень суровые связи. Они не паталогические (потому что так и задумано), но очень WTF'ные при отладке.
Что такого делает Author-It или MadCap Flare, что за них готовы платить $150 в месяц, но их можно заменить простой wiki?
Они дают WYSIWYG-редактор и обеспечивают (как уж могут) жизненный цикл документации (разработка-ревью-публикация). За счёт визуального редактора на них можно за день пересадить человека, который писал только в Ворде до этого. То есть, требования к квалификации писателя минимальные.
Ещё в них из коробки могут быть какие-то полезные фичи: поиск, аналитика, красивая тема оформления. Но это будет свой закрытый вендорский поиск, с починкой багов по пять лет и невозможностью что-то самому поправить.
Это XML со всеми его проблемами. Использование XML-based технологий не устраняет стену между техписателями и разработкой. По-прежнему нужно иметь специальный редактор и знать конкретную нотацию, чтобы контрибьютить в документацию. А ещё XML плохо мержится и диффается. Ну и самое главное, это более сложный инструмент, а результат условно тот же.
Однако, XML-based технологии хороши, когда у нас высокая степень переиспользования контента и/или очень много метаданных. Например, мы формируем инструкции для 1000 единиц бытовой техники, используя для этого 3000 кусочков контента. Или у нас продукт в области инфобезопасности, у него 5 активных версий и 10 ролей пользователей, которым доступны или не доступны разные фичи. Тогда мы размечаем документацию по тому, какие фичи она использует, и к каким версиям продукта подходит. А потом собираем вот эти 50 руководств для разных ролей и версий. Тут XML хорош, потому что в нём удобно навешивать метаданные на контент.
Из коробки, похоже, нет такой возможности. И у нас ни разу не было потребности в этом. Но Sphinx легко расширяется, так что можно написать свой экстеншен. Вот пример: https://stackoverflow.com/questions/57271548/custom-section-numbering-in-sphinx, https://github.com/sphinx-doc/sphinx/issues/6614.
Ну и я бы посоветовал освоить работу с патчами и 3-way merge. После этого можно начать движение в сторону источников контента — тесткейсов, юзер сториз, спек, тикетов и где там еще у вас ведется внутрипроектная документация. Если технически возможно и удалось договориться с командой на разметку и редактирование нужных вам блоков текста в оригинальном источнике — в выигрыше и команда и вы. Не удалось договориться — все равно можно выдернуть данные из источника — и наложить патч дополняя текстом например наборы команд из тесткейса, ну и заодно убрать ненужные детали. Если источник сильно поменялся — патч просто не применится.
Ну и самое главное — документация перестанет быть самостоятельной сущностью со своим независимым жизненным циклом, который приходится принудительно синхронизировать с SDLC.
А почему вы не конвертируете MD в RST и не пускаете все по одному пайплайну
Финальную сборку сайта делает Jekyll, а он в качестве исходников контента принимает именно MD. Исходники страниц вроде release notes у него в чистом MD + frontmatter в шапке. А страницы документации мы* сначала Sphinx'ом собираем в HTML, потом выделяем из него кусок HTML с контентом и тоже добавляем frontmatter. Тут можно вспомнить, что MD это надмножество HTML, так что по сути Jekyll собирает окончательный сайт из MD. Так что пайплайн сборки как раз конвертирует rST → MD.
*в Plesk я уже не работаю, так что это «мы» по старой памяти :)
Ну и я бы посоветовал освоить работу с патчами и 3-way merge
Пока непонятно, какую проблему это бы решило.
источников контента — тесткейсов, юзер сториз, спек, тикетов и где там еще у вас ведется внутрипроектная документация
Внутрипроектная документация пишется совершенно другим языком, с другими целями и для другой аудитории. Нельзя взять и выложить её клиентам. В роли пользовательской доки она будет бесполезна или даже вредна. Написать пользовательские доки с нуля проще и быстрее, чем взять и отредактировать проектную документацию.
Ну а ещё, внутренние доки не обязательно пишутся в разметке и лежат в репозитории с кодом. В большинстве известных мне компаний это не так.
Использование внутрипроектной документации как начального источника — позволяет опереться на элементы, которые и в пользовательской документации и во внутрипроектрой одинаковы, типа вывода командной строки, скриншота, названия элемента интерфейса и т.д. И при включении блоков пользовательской документации во внутрипроектную — этот текст ревьювится и обновляется еще на этапе проектирования.
Преобразовать любую внутрипроектную документацию в текст и выкинуть лишнее — эта задача вполне автоматизируется даже без патчей. А с патчами появляется возможность автоматизировать добавление и изменение текста (когда с командой не удалось договориться про включение пользовательской документации во внутрипроектную). При значительных изменениях внутрипроектной документации — патч ломается, сразу показывая необходимость ручной правки.
Когда все блоки текста пользовательской документации готовы и отревьюваны — сборка финальной версии тоже прекрасно автоматизируется. В результате пользовательская документация может собираться в виде одного из шагов буквально для каждого билда.
Ну и могу предположить, что многие разработчики, как и я, пользуются шаблонами при написании текста, производя тонны квадратно-гнездового текста просто потому что не выделяются талантами на ниве писательства. А уж когда и язык в добавок иностранный…
И с удовольствием воспользуются своевременной помощью при создании внутрипроектной документации.
Выбираем инструменты для docs as code, приглянулись Docusaurus и Sphinx, но стоит вопрос разграничения прав доступа (в идеале настраиваемый доступ по группам для каждой статьи, но хотя бы деление на статьи внутренней и внешней документации). Пока есть ощущение, что это потребует отдельного репозитория или ветки для каждого варианта. Может быть кто сталкивался с такой задачей, есть ли похожие инструменты со встроенной поддержкой прав доступа?
Объём контента пока небольшой, так что можно и вручную, но хочется попробовать этого избежать.
Docs as Code: введение в предмет