Comments 17
Ну вы молодцы и зайки, если статья была написана для похвалы, то держите, вот она. А нам-то с этого какой профит? Попробовать где-то можно?
Возьмите карту до 120 дней без процентов(возьмём с вас по дружбе, не много).
Еще положите денег. Получите доход (без процентов).
И тогда Вам покажем скриншоты.
Добрый день! Мы поделились опытом, который можно применить для решения практических задач. Надеемся, что информация полезна всем, кто разрабатывает подобные системы или находится на этапе выбора инструмента документирования. Также рассказали о новом продукте в линейке Platform V. Если продукт вас заинтересовал, мы можем провести демо. Оставьте, пожалуйста, заявку на нашем сайте https://platformv.sbertech.ru/products/prikladnye-produkty/get-docs.
здорово что спички на кдпв уложены поперек а не вдоль, значит их еще и обрезать пришлось
Для больших компаний такое правильно и часто встречается. (Хотя в статье переусложнено как по мне)
Хотя чаще есть отдельный человек что занимается ведением всех технических данных (и техническ й стек глубоко вторичен).
Таблицы и прочее прочее, нужны больше для пояснения функционала и прочих данных верхнего уровня. Когда документация "низкого уровня" всегда попоболь, так разрабатывается и правится.
.
У нас на работе есть частая задача с созданием и модифицированием АПИ в огромных обьемах.
Прошли через многое.
На сейчас реализована обратная система - из openAPI файла генерируются методы роута, со всеми проверками что описаны в openAPI. Если валидация верна то результат передается на метот указаный в openAPI (х_ параметр) или на типовую заглушку если метот не указан.
Такой подход очень сильно упростил жизнь:
Количество проблем с выкаткой обновлений, которые не соотвествуют стандартам безопасности или не соотвествуюет документации сократилось до нуля
Единый вид валидации и обработки всех перехватов.
Програмисты работают именно над реализацией функционала, а не занимаются "творчеством" в пространстве между сервером и клиентом.
Добавление новых методов или модификация старых требует только работу с документацией. Нет "лишней работы" которую так не любят разрабы. Все что делается влияет на работу и отображается в документации, без дублей.
Гибкая работа с версиями АПИ или разными точками входа, в одном приложении. Разные методы могут отдавать один и тот же результат и работают с одним и тем же методом.
Документацию можно открыть в любом удобном виде, так как это открытый стандарт.
Конешно не обошлось и без минусов:
В openAPI нет веб-сокетов. Пришлось "придумать" свои костыли описания и уже который год с ужасом "предвкушаем" когда в стандарте он появится.
Пришлось отказатся от не строгой типизации, когда параметр может принимать несколько разных видов данных, потому как это переусложняло и запутывало. Старые версии поддерживают, но новые уже нет.
Создалось более двух десятков новых параметров которых нет в openAPI но которые необходимы нашему парсеру для работы. Для работников пришлось писать документацию на документацию)
Для тех кто привык работать с системами автодокументирования было сложно переключится на новый формат. Доходило до споров и даже одного увольнения.
Такой формат работы с "черными ящиками" заставляет програмистов быть более сфокусироваными. Тесты генерируются вместе с роутами и проверками, потому нельзя "набросать" готовое решение и сказать "ясделял".
Занимаюсь сейчас примерно тем же самым, но пока в начале пути :) Поэтому пару вопросов
Sphinx из коробки не умеет генерить docx, что вы для этого используете? Делали свои шаблоны для публикации docx документов?
Не совсем понял, зачем комбинируете rst и md? Rst побогаче будет. Md обычно берут, если нужно попроще.
Как работаете со сложными таблицами? У нас аналитики любят в конфлюенсе использовать вложенные таблицы - как вы их "парсили"? Я пробовал просто экспортировать в ворд, а потом пандоком в рст, в целом получается неплохо, но приходится дорабатывать напильником.
Для генерации DOCX мы используем Pandoc, набор lua- и python-фильтров для поддержки разметки MyST Markdown.
MyST выбрали, потому что у MD ниже порог входа, чем у RST. Можно писать на обычном MD и только при необходимости начать использовать дополнительные директивы. В компаниях, где большое число пользователей с разным бэкграундом, выгоднее выбирать простую разметку. Чем легче разметка, тем проще начать писать. А у нас еще часто сжатые сроки на написание документации. Простота инструмента дает возможность эти сроки выдержать. MyST дает полную поддержку директив RST, поэтому в любой момент можно перейти на расширенный синтаксис и начать пользоваться дополнительными директивами.
Сложные таблицы оформляются либо директивой flat-table (https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#flat-table). Также можно делать таблицы в HTML-формате, но мы не рекомендуем этого делать.
Ответ на главный вопрос почему из заглавия: потому что "выгодно". Почему это "выгодно" осталось загадкой :-)
Здравствуйте, спасибо за то что поделились опытом. Скажите пожалуйста, будет ли этот инструмент доступен для внешних пользователей? Также интересно, как именно вы используете Vale для русского языка. Вы просто ищете русскоязычные слова как последовательность символов, или же у вас есть свои наборы более высокоуровневых правил?
Здравствуйте, продукт коммерческий. Мы можем провести демо и подробно рассказать о функциональности. Оставьте, пожалуйста, заявку на нашем сайте https://platformv.sbertech.ru/products/prikladnye-produkty/get-docs.
Валидатор в составе продукта включает набор из нескольких отдельных специализированных валидаторов. В Vale-валидаторе используем регулярные выражения для правил, которые хорошо формализуются. В основном это правила из нашего руководства по стилю, но не только. Также есть набор валидаторов собственной разработки, некоторые из которых используют ИИ. Мы планировали посвятить этой теме отдельную статью, которую опубликуем ближе к осени.
А этот некий движок получается создаёт просто сайтик с конкретной версией доки, а если хочется как у postgres? В самой доке содержится куча версией между которыми можно переключиться.
Наш сборщик формирует сайт документации на все продукты. Генерируется каталог со списком всех продуктов, и для каждого продукта отдельный раздел, где можно выбрать документацию нужной версии продукта.
Сайт выглядит вот так https://client.sbertech.ru/docs/public/
Спасибо, а скачать и протестировать-то где?
Победить хаос в документации: почему мы создали свой продукт для Docs-as-a-Code