Комментарии 18
Благодарю за статью, прочитал с интересом подход.
В силу своей должности с документацией работаю постоянно.
Озвученная вами боль известна очень хорошо :)
Маркдаун имеет свои преимущества, однако, большая часть коммерческого ПО имеет визуальный интерфейс в том или ином роде, который в вашей статье не подсвечивается.
Как итог:
1) Как вы будете хранить информацию о дизайне в маркдауне?
Есть же страницы с динамическим наполнением, а не только статичная HTML.
По сути вам придется делать ровно тот же хаос, который существует в папке любого проектного менеджера.
Версия 1, версия 2, версия 122.
Кстати, из практики, нумерацию в таких случаях проще вести не в версиях, а в датах обновления.
"20250620_Главная страничка"
Тогда внутри папки файлы всегда ложатся в хронологическом порядке и легко фильтруются.
final и прочие надписи - путь в пучину легаси без документации :)
2) ТЗ коммерческого сектора в том или ином виде предполагает наличие User Flow, которое предполагает наличие картинок/референсов/макетов, которые предполагают, что они где-то как минимум должны быть постоянно залинкованы.
Разработчик ушел, сервер потушен - ваша документация умерла, потому что отвалились все картинки.
Аналогично фигма.
Как итог - картинки должны быть доступны локально в 100% случаев.
Т.е. сам файл документации должен хранить внутри себя все картинки и их расположение без деплоя кода на сервер.
По итогу предложенный вами вариант - очень интересная тема для менеджеров из IT (бывшие тимлиды и разрабы, например), которым привычен маркдаун.
И вообще не работает для простых менеджеров (обычный руководитель среднестатистический после курсов "IT за 2 часа", коих, наверное, большинство сейчас).
Попробуйте подумать и в сторону UI-документации для полного охвата любого проекта и будет нам всем счастье :)
Из моей практики лучшим сочетанием пока является:
1) Маркдаун для технической документации
2) pptx для всей остальной
Если вам известно что-то более интересное, то буду рад взаимовыгодному диалогу :)
А ресурсы в pptx ручками по одному обновлять? Так а чем тогда какой-нибудь odt формат от OpenOffice Wrirter не подходит? Та же фигня, но с возможностью автоматизации (через боль, но все же) и экспорта во что угодно. От HTML и PDF до богомерзкого .doc.
Я именно там подобную документацию делал. Из плюсов - иерархия стилей и нумерации, которая позволяет сохранять однообразие представления и быстро править структуру документа (когда у вас в разделе из ста пунктов новый пункт добавился и при этом ещё и нумерация разделов изменилась).
В нем реально можно зафигачить документацию из четырёх связанных документов на 250 страниц с картинками и таблицами, а потом поддерживать её в актуальном состоянии на протяжении нескольких лет, по мере эволюции продукта. Хотел бы я посмотреть, как вы это в своём pptx исполните.
OpenOffice не использовал, подсказать не смогу :)
Но посмотрю, что имеете ввиду.
По ресурсам да - ручками, как и в маркдауне придется правки вносить.
Тут вариантов не шибко много :)
Если под автоматизацией понимается пуш в гит, так pptx тоже можно класть, как и любой файл - ничем не отличается и ровно таким же образом процесс CI-CD настраивается.
Другой момент, что одновременно править нельзя будет файл, так как смеджить содержание pptx не выйдет.
Из преимуществ pptx имеет возможность вставить картинку "как элемент" и настроить его расположение.
Т.е. не линк на картинку, а именно изображение внутри.
Аналогично с файлами можно поступать.
А при необходимости их оттуда можно забрать в исходном виде.
В частности макетирование сайта можно сделать с кнопками-переходами (ссылка на страницу документа).
По итогу получаем UI кликабельный в режиме демонстрации, который можно тыкать самому, а может тыкать заказчик.
Из практики очень хорошо заходит у заказчика на первых этапах проектирования структуры, так как за 1 день заказчик получает возможность визуализировать то, что он хотел.
Получаем макет на минималках, в котором без участия разработчиков может даже сам заказчик переместить объекты так, как ему нравится.
Иногда в процессе оказывается, что не хватает кнопок перехода и т.п.
Быстро, дешево, удобно.
Даже примитивную анимацию можно делать а-ля смена цвета кнопок, если время позволяет :)
.doc, на мой взгляд, только для юридических документов можно использовать, потому что по итогу в режиме редактирования там юристы и переписываются дополняя друг-друга, стандартная форма их коммуникации.
В маркдауне они писать принципиально не будут.
И опять же, финальный файл спокойно вкладывается в pptx именно в виде файла (не линком).
Для ведения документации пробовал - выходит мрак :)
Я к тому, что файл pptx выступает как своеобразный локальный архив, внутри которого лежат без линков все нужные версии файлов, которые по тем или иным причинам нельзя положить в маркдаун :)
а) Независимость от вендора
б) Независимость от сервера
в) Дублирование у разработчика и заказчика гарантирует сохранность
Как писал выше:
1) Маркдаун основа
2) pptx для всего, что имеет визуал + что не влезло в маркдаун.
Изображения, макеты, схемы нестандартные и т.п.
Но опять же, если какие-то иные инструменты есть - только за.
Проект без документации при длительной поддержке - это боль :)
Спасибо за ваши комментарии! Я не очень поняла, какие сложности могут возникнуть с картинками, постараюсь опираться на тезис "сам файл документации должен хранить внутри себя все картинки и их расположение без деплоя кода на сервер". Сейчас расскажу, как это устроено.
В Gramax вы можете добавлять в статьи:
- Диаграммы.
- Любые картинки.
- Видео.
Диаграммы и картинки
Сам файл диаграммы или картинки сохраняется в репозитории в исходном виде. В Markdown-файле статьи сохраняется путь до ресурса (диаграммы или картинки) в репозитории.
Это позволяет нам работать локально: при загрузке всего репозитория у редактора корректно отображается как статья, так и все ее ресурсы.
Так как ресурсы хранятся в самом репозитории, ситуация "Разработчик ушел, сервер потушен - ваша документация умерла, потому что отвалились все картинки" невозможна.
Видео
Так как хранить в репозитории большие файлы (а видео обычно большие) не очень хорошая практика, мы позволяем в редакторе добавить ссылку на видео из любого источника с возможностью стриминга. Это может быть YouTube, RuTube, DropBox и так далее. Видео как раз является этим динамическим элементом, о которых вы писали. Понятное дело, что в PDF оно не воспроизведется, но ссылка сохранится и по ней можно будет перейти.
Информация о дизайне
В статье мы описываем документацию, которая передается после завершения проекта. Это, как правило, руководство пользователя, администратора, техническая спецификация. На этом моменте нет потребности согласовывать дизайн. Описать юзерфлоу — да, нужно. Но это делается в стандартной форме инструкции или туториала, где фокус не на элементах интерфейса, а на действиях пользователя.
Нумерация версий
Версии документации, в идеале, должны соответствовать версиям продукта. Каждая версия хранится в отдельной ветке. Например, из ветки v1.1.0 мы создадим ветку v1.1.1 и добавим в нее новые фичи + описание этих фич.
Ограничения Markdown
Да, обычный Markdown довольно скуп на оформление. Поэтому мы самостоятельно его расширили: добавили сложные таблицы, яркие заметки, вкладки и другие необходимые элементы. Так как даже с нашими расширениями он может подойти не всем, постепенно расширяем и поддерживаемые языки разметки: например, недавно добавили MDX (Markdown + XML) и GitHub Flavored Markdown (для тех, кто оформляет README в GitHub). Постепенно будет добавлять и другие языки.
Надеюсь, правильно поняла вопросы и понятно на них ответила. Ну и не могу упустить возможность написать, что полезных и приятных возможностей у нас много. О них подробнее можно узнать в документации:
https://gram.ax/resources/docs
Благодарю за ответ, давайте тогда пробовать разбираться по элементам :)
Диаграммы и картинки
Сам файл диаграммы или картинки сохраняется в репозитории в исходном виде. В Markdown-файле статьи сохраняется путь до ресурса (диаграммы или картинки) в репозитории.Это позволяет нам работать локально: при загрузке всего репозитория у редактора корректно отображается как статья, так и все ее ресурсы.Так как ресурсы хранятся в самом репозитории, ситуация "Разработчик ушел, сервер потушен - ваша документация умерла, потому что отвалились все картинки" невозможна.
Предположим, что я внешний разработчик (компания) и веду разовые работы на своем компанейском git.
В определенный момент мне потребуется полностью все передать в git заказчика (сдать работу).
Мне свой git поддерживать уже не имеет смысла (работа сдана).
Так как все ваши пути "до ресурса" будут залинкованы на мой git, то в определенный момент вы, как заказчик, имеет серьезный риск потери всех картинок.
При этом перелинковка потребует значительных усилий, так как по сути нужно будет поменять каждую ссылку в документе (по сути ревизия всей документации).
А бизнес не платит за переделку документации к рабочему продукту :)
Видео
Так как хранить в репозитории большие файлы (а видео обычно большие) не очень хорошая практика, мы позволяем в редакторе добавить ссылку на видео из любого источника с возможностью стриминга. Это может быть YouTube, RuTube, DropBox и так далее. Видео как раз является этим динамическим элементом, о которых вы писали. Понятное дело, что в PDF оно не воспроизведется, но ссылка сохранится и по ней можно будет перейти.
Видео - интересная идея.
Однако хранить документацию (а видео тут выступает в этом контексте) на внешних хранилищах вообще недопустимо, как минимум с точки зрения ИБ.
Ни один сервис не гарантирует вам недоступность вашей ссылки.
Как итог - есть неплохой шанс открыть всему миру полное описание того, как работает сервис на уровне админа, что дает хороший такой вектор атаки для хакера.
Информация о дизайне
В статье мы описываем документацию, которая передается после завершения проекта. Это, как правило, руководство пользователя, администратора, техническая спецификация. На этом моменте нет потребности согласовывать дизайн. Описать юзерфлоу — да, нужно. Но это делается в стандартной форме инструкции или туториала, где фокус не на элементах интерфейса, а на действиях пользователя.
Из практики:
юзер флоу без дизайна (хотя бы в виде набросков) - путь к переделкам.
Текстовое описание никогда не сможет конкурировать с примитивным макетом в силу того, что менеджеры на стороне заказчика являются простыми менеджерами, а не техническими специалистами.
Им требуются картинки для наглядности и согласования.
Чисто текстовое описание приводит к разрыву "ожидание-реальность", что по итогу может сорвать вообще весь проект.
Нумерация версий
Версии документации, в идеале, должны соответствовать версиям продукта. Каждая версия хранится в отдельной ветке. Например, из веткиv1.1.0мы создадим веткуv1.1.1и добавим в нее новые фичи + описание этих фич.
Теперь представьте простого среднестатистического менеджера, которому вы говорите "Сходите в гит, в ветку dev_v1.1.1, сделайте pull изменений к себе, чтоб получить обновление документации по вашей фиче".
Все что будет понятно менеджеру - слово "документация" и ответом менеджера станет "пришлите на почту".
Пользоваться гитом простой менеджер заказчика не будет, а документация при этом ему требуется.
На это я ранее и указывал, что документация в маркдаун - это документация для технарей, но, к сожалению, ее сложно приспособить для нужд менеджеров или юристов.
Они мыслят pptx и doc, к сожалению.
Отсюда и все ТЗ во всех тендерах в виде doc-файла и pdf.
И с этим требуется как-то дружить :)
Надеюсь, правильно поняла вопросы и понятно на них ответила. Ну и не могу упустить возможность написать, что полезных и приятных возможностей у нас много.
О них подробнее можно узнать в документации:https://gram.ax/resources/docs
В любом случае спасибо за продукт,
думаю, что он уже занял свою определенную нишу или займет ее далее.
Мои комментарии - это больше история про универсализацию продукта.
На данный момент мне кажется, что этот продукт больше подходит для технарей (внутренней документации) и полностью не подходит для заказчика (в силу того, что он не сможет с ним адекватно взаимодействовать).
Как итог, придется вести двойную документацию, что нарушает саму концепцию единого документа для всех.
Однако мое мнение субъективно и пока основывается лишь на вашем описании в статье и комментариях.
Как будет время - изучу поподробнее ваш продукт и, может быть, вернусь с опровержением своих слов :)
Я пишу документацию для себя, пробовал разное. Начинал с маркдауна. Его просто не хватает на что либо. После мардауна был асидок. Это было намного лучше, но потом познакомился с typst. И этот вариант зашел на ура. Встроенный парсер json, csv позволяет хранить файлы на основании чего генерировать текст. Возможно создавать свои функции. Нужен например note, создал. Надо изменить, изменил функцию. Довольно простая документация и многое другое
Для личных заметок есть obsidian.md/. Это редактор, где маркдаун довели до абсурда абсолюта. Там из маркдауна через платины можно ходить хоть в базу, хоть в API, хоть в AI.
Как вы верно указали обсидиан это для личных заметок, я же говорю о рабочей документации. В случае моего отсутствия коллеги открыть пдф файл сумеют, при чем на своем устройстве. Да и городить огород с кучей директорий обсидиана как то не хочется.
Да, в стандартном Markdown особо с оформлением не побалуешься. Я выше писала, что мы тоже с этим столкнулись. И сначала расширили его самостоятельно (добавили заметки, гибкие таблицы, вкладки и многое другое), а потом начали поддерживать другие нотации Markdown (MDX и GitHub Flavored Markdown).
Что еще в планах:
1. Продолжить расширять поддерживаемые языки разметки.
2. Сделать механизм подключения кастомных модулей на TypeScript. Чтобы пользователи могли самостоятельно расширять или изменять приложение под требования компании/команды.
Мне, честно говоря, маркдауна на всё хватает. Ты просто подстраиваешься под его особенности и не пытаешься нарисовать в нём многомерную таблицу или типа того. Это позволяет подходить к написанию требований иначе, декомпозируя их и раскладывая по полочкам.
А вот то, что каждый, кто взял маркдаун за основу начинает напихивать в него собственную кастомизацию - это тригерит слегка. Яндекс свои правила использует, грамакс - свои. И никто даже не делает теги скрытыми(хотя это есть в маркдауне). В результате взаимной совместимости примерно ноль. Чтобы перенести маркдаун из яндекса в граммакс надо изрядно попотеть... А маркдаун из грамакса использовать где-то ещё (например просматривать из под гитлаба) тоже невозможно. Это расстраивает и добавляет "минусов" при выборе инструмента...
Смотря о каком маркдауне речь. Основа – это CommonMark. Всё остальное – вариации. В CommonMark не так много элементов и даже нет таблиц, про которые вы говорите :) Пруф: https://commonmark.org/help/
Грамакс нативно поддерживает GitHub Flavored Markdown. Можно писать только на GFM через визуальный редактор.
Но эта вариация также весьма ограничена и если нужно больше, то можно использовать вариацию маркдауна от Грамакс или Яндекс.
Екатерина, а почему не используете формат DITA?
По сути в DITA включены простые понятия по структуризации, параметризации и переиспользованию контента. Но существующий инструментарий требует колоссального труда для поддержания доки.
Поэтому мы реализуем эти понятия в удобном визуальном редакторе, чтобы любой специалист мог работать с продвинутой документацией быстро и просто.
P.S. При обсуждении DITA всегда вспоминаю мнение @arinaballerina:
Дита прекрасна, но да, понадобится отдельный сотрудник, который всё это настроит, включая XSLT преобразования, и будет поддерживать. Такой спец будет стоить недёшево, и вопросов у него будет года на два работы.
Тут заговорили про разные альтернативы: obsidian, gitbook и т.п. и возведение идеи в абсолют. Я же для себя решил что все существующие wiki черезчур усложнены. Я хочу: писать markdown в своём любимом редакторе, использовать git для версионирования и иметь доступ к результату через web. Все. Больше мне ничего не нужно. Так появился gitiki (уж не сочтите за рекламу :-). Вот это я считаю возведения идеи в абсолют.
А можно просто мой README.md превращать в pdf с моим .ott шаблоном? Или например передам бренд бук в pdf и в соответствии с ним будет происходить превращение?
Передаем документацию заказчику: Markdown, Git, CI/CD и почти полная автоматизация