Comments 32
Я тут недавно столкнулся с необходимостью печати markdown, причём у меня в нём было много таблиц по 5-6 столбцов и 30-40 строк, markdown конечно очень слабо приспособлен для такого большого количества данных, огромные отступы в каждой строке рисует любой вьювер, в итоге я справился при помощи https://www.npmjs.com/package/md-to-pdf, но пришлось стили покрутить конечно. Причём изначально у меня эти данные существуют в виде модели, и я ещё выбирал как проще всего мне из подготовить к печати, можно было конечно сразу html генерировать, но не хотелось возиться. В случае с маркдауном сложно повысить плотность представления информации на листе.
Obsidian+Hugo?
И да и нет - тут нужно понимать, какой функционал пересекается и как оно работает. В какой-то части похоже, в какой-то нет, в третьей - вообще по-другому.
Обсидиан это такой большой-большой комбайн и больше подходит на роль инструмента - редактора (сам пользуюсь для своих личных заметок). Точно так же тут может быть VSCode, Sublime/Vim с плагинами - маркдаун тем и хорош, что можно где угодно редактировать, инструмент не сильно важен.
Если про генератор и хостинг статики - тут при желании можно реплицировать наш функционал в Hugo и наоборот - сделать из нас Hugo. Вопрос усилий и целесообразности.
Мы все-таки даем платформу которую можно использовать целиком (получить работу с Вашей документацией как с кодом из реп в github ) или взять кусочками (и внедрить в Ваши пайплайны внутри организации с какими угодно VCS) - мы достаточно гибки, чтобы удовлетворить большинство кейсов с продуктовой и технической документацией. И стремимся сделать это максимально просто для всех потребителей.
В опенсорсе что-то есть, но как пользоваться? Судя по сайту - только "свяжитесь с нами и мы вам всё сделаем". А зачем?
Так работает любой бизнес
"А зачем?" относится к "свяжитесь с нами"? Или какому-то другому аспекту?
Если про "свяжитесь с нами" - тут все довольно просто:
С точки зрения коммьюнити и пользователей - инструмент новый, могут возникать трудности его применения и мы будем рады помочь его правильно приготовить. Особенно, если есть какая-то специфика по работе с документами в ci/cd, о которой мы можем не знать. Из своей жизни разработчика помню случай, когда провел две бессонных ночи за дебагом того, что дебажить не нужно было - нужно было лишь спросить коллегу, зачем в той структуре именно так битовое поле определялось...
И такие штуки могут быть не описаны в типовых сценариях. А может - мы упустили такое поведение, потому что глаз замылился или слишком очевидно, чтобы добавить пару строк. А может - у Вас такой сложный пайплайн, что мы не сможем удовлетворить все Ваши нужды сразу и придется дать какие-то рекомендации, чтобы что-то допилить. Поэтому мы сейчас очень сосредоточены на сборе фидбека и сценариев использования, чтобы помогать и организациям и отдельным людям. "Связаться с нами" или прийти в телеграм - отличные точки сбора полезной информации, особенно для open sourcе продукта и корректировки вектора развития.
При этом не стоит забывать и о документации для Diplodoc - вы можете влиять на эту документацию, приносить пулреквесты, давать замечания и пожелания - мы обязательно учитываем все запросы. Это тоже своего рода канал связи с нашими пользователями - мы продолжаем активно работать над структурой и описанием того, что максимально полезно потребителям.
Ну например я хочу для своей команды захостить небольшой внутренний сайт с информацией о работе, процедурах и прочем.
Сейчас всё сделано на Hugo и всё выглядит очень неудобно. Ваше решение выглядит крутым, однако я не могу просто взять его и заиспользовать - нужно куда-то писать, о чем то спрашивать, т.к. явной инструкции по использованию нет. Для чего нужны искусственные препятсвия мне решительно непонятно :(
- … мы выбрали Markdown… вставлять… заметки, каты, видео, табы, всплывающие подсказки, документацию.
- Хранить… в любом другом репозитории… удобно править и дополнять.
- … создаёт… файлы в формате HTML.
- … собирает из набора html-файлов готовый статичный документационный проект.
- … автоматически перевести...
Теперь вопрос. Мне кажется, что всё это уже есть в MediaWiki. Почему ваше решение оказалось лучше?
Спасибо.
Вы знаете, я начал писать и остановился в тот момент, когда размер комментария начал превышать размер первоначальной статьи - значит, в скором времени будет еще несколько об управлении знаниями, типах документации и инструментах для решения задач в вышеозначенных контекстах. Но это так, лирическое отступление и спасибо за комментарий!
TL:DR; MW в первую очередь предназначен для хранения всевозможной структурированной и неструктурированной информации(можете считать MW своего рода DataLake для данных, целевое назначение которых пока непонятно). Diplodoc - для работы с документацией. Информация и документация все-таки разные вещи и жизненный циклы у них разные.
Если вкратце, то документация бывает разная - техническая, пользовательская, маркетинговая, етс. Пример: напротив меня сейчас стоит утюг.
Техническая и архитектурная документация у меня для него отсутствует. Она где-то на заводе Tefal, надеюсь.
User guide в виде брошюры на разных языках является пользовательской документацией.
Красивые пара цветных листочков в коробке и сама коробка -примеры маркетинговой.
У каждого из этих типов документов свой цикл разработки, подразумевающий разные инструменты создания, валидации и публикации.
Идем дальше, в любой организации есть n источников информации, который отличен от нуля. С ними работают по-разному - с какими-то более формально, с какими-то менее. Примеры:
внутрекорпоративная вики представлена решениями типа mediawiki, confluence, где можно сохранять все и как угодно. Хотите файлы, хотите картинки, хотите текст. Это - гибкость, за которые подобные инструменты любят и используют. Обратной стороной гибкости и демократизации внесения данных является бардак - часто информация неструктурированна, не соединена в общий стиль логического повествования и отображения, разнесено по разным нодам в дереве. Публикация в подобных решениях, как правило, не требует никаких согласований или валидации.
внутренняя или внешняя база знаний. Может быть сделана на битриксе, той же самой confluence или самописных решениях. Особенностью этих инструментов является более четкий подход к формату и структуре статей. Причина заключается в том, что от качества статей сильно сокращается когнитивная нагрузка при обращениях пользователей или смежников. Отсюда и требование - статьи должны проходить валидацию и получать sign-off от владельцев описываемых систем или продуктов.
А еще есть системы по работе со справкой(тот же самый битрикс) системы корпоративных блогов (типа яммера или самописного), внутренние соцсети и форумы...
Все это превращается в огромное информационное поле, которое бурлит и обновляется ежесекундно, но получить оттуда структурированную, четкую и полезную информацию бывает сложно.
Простите за долгое повествование, хотел показать, что не всегда получается сравнивать инструменты работы с документацией и информацией напрямую, даже если они используют схожие технологии. Системы могут пересекаться по функционалу очень сильно и каждый инструмент имеет тенденцию к росту, что еще больше запутывает.
Мысль заключается в том, что Diplodoc предназначен для работы с документацией как с кодом изначально. Это значит, что он является частью Вашего процесса разработки и следует тем же правилам и этапам - от создания текста до публикации. Это правила, это структура, это единый подход к построению документации. Для нас это оказывается сильно проще и эффективнее, вот часть причин:
формат md, простой и обрабатываемый одинаково. Добавился какой-то новый функционал - это появляется сразу везде.
встраивание в пайплайн разработки и разные интересные связанные возможности (что-то вроде идеального - "делаешь коммит в коде, будь добр, обнови свяазанную доку, иначе билд не пройдет").
структура документов, отточенная годами и улучшающая взаимодействие между авторами и читателями. Особенно важно для справки, например, большого Яндекса.
куча автоматизации, убирающая боттлнеки внутри и снаружи при билдах и деплоях.
...
Я отмечал в одном из предыдущих комментариев - при желании Вы можете превратить MW в Diplodoc, тем более что оба решения опенсорсные. Обратное - тоже возможно, но не уверен в целесообразности. У нас нет цели превратиться в еще одну Wiki, мы напротив - стараемся уменьшить энтропию.
Еще раз прошу прощения за длинный коммент.
Обратной стороной гибкости и демократизации внесения данных является бардак — часто информация неструктурированна, не соединена в общий стиль логического повествования и отображения, разнесено по разным нодам в дереве. Публикация в подобных решениях, как правило, не требует никаких согласований или валидации.
Вы рассказали про административные признаки. Если начальник приказал не структурировать информацию, приказал не покрывать её общим стилем, приказал разбрасывать, тогда всё это появится. Если начальник приказал не согласовывать и не проверять, тогда не будут согласовывать и проверять.
А если начальник приказал иначе, тогда в MediaWiki всё будет иначе.
Отсюда и требование — статьи должны проходить валидацию и получать sign-off от владельцев описываемых систем или продуктов.
Это требование появляется не от программирования движка, а от приказа начальника.
нет цели превратиться в еще одну Wiki, мы напротив — стараемся уменьшить энтропию.
Правильно ли я понял, что если начальник приказал ничего не валидировать, не проверять, избегать структуры, если начальник отменил подзаголовки, если начальник требует писать вразнобой и ничего не согласовывать — тогда программа Diplodoc окажется сильнее такого начальника? Тогда программа Diplodoc уволит его?
Неужели вы написали инструмент, который умеет захватывать власть на предприятии?
Простите, не совсем понимаю Ваши выводы и вопрос.
Если ожидается прямой ответ - конечно нет.
Если это сарказм - ок, мы подумаем над таким функционалом в будущих релизах. Генеративные модели довольно хороши сейчас.
На самом деле, если Вы хотите сравнить именно Wiki решения и как с их помощью можно создавать KB - тут есть большой простор - можете попробовать https://wiki.yandex.ru/.
Правда, отмечу, что исходники пользовательской документации для Wiki лежат в гитхабе в маркдауне, а сборкой и выдачей этой справки занимается движок Diplodoc (вот тут, например).
Я хочу понять, почему разговор начался с обсуждения технологии, а теперь пришёл к администрации. Все названные вами недостатки MediaWiki относятся не к программе, не к серверу, не к данным, а только к управлению людьми.
Порядок возникает не из движка, а из поставленной задачи. Если поставлена задача навести порядок, MW позволяет это сделать. Но если поставлена задача сохранить разнобой и путаницу, разве ж Diplodoc помешает этому?
Мне все-таки кажется, что мы немного о разных вещах говорим.
Во-первых, прошу прощения если где-то MW приписал недостаток.
"Бардак" - это одна из важных частей Вики в той или иной реинкарнации, за это ее и любят и ненавидят. Отсутствие структуры позволяет каждому выражаться так, как хочется. В собственном пространстве - особенно. Совместная работа над документами, история - все великолепно.
Только потом это потенциально превращается к кладбище информации и данных, без внятного механизма актуализации и поиска.
И Вы абсолютно правы - если руководство поставит задачу "чтоб было все в порядке" - наверное, так и будет. Я, честно говоря, не встречал еще такого реализованного полностью на своем веку, но это мой опыт такой.
Во-вторых, Вы смотрите на Diplodoc как замену MW в контексте работы с контентом в коллаборативном режиме. Diplodoc не заменяет Wiki и цели такой нет. То, что есть инструментарий, который позволяет воспроизводить часть функционала - да. И вы можете видеть этот функционал и в вики Яндекса и еще паре мест. Но основная задача - это работа с документацией как с кодом. Если MW может это делать - это отлично, надо будет посмотреть как они хуки обрабатывают при работе с гитхабом.
В-третьих, инструменты и технологии могут помогать, а могут мешать выстраиванию порядка или процессов. Diplodoc помогает.
Документация в репозитории, при изменении она проходит ревью как обычный код с diffами, билдится в документационный проект и отдается потребителю. Понятный четкий пайплайн от начала и до конца, он существует в организации и не требует переключения контекста для разработчиков. Вы можете редактировать и код системы и документацию в одном редакторе, эти изменения положить в один коммит - и вот у вас уже готовый продукт, побилженный и лежащий в хранилище артефактов вместе с обновленной и побилженной докой.
Это помогает сохранять порядок, но, конечно же - не панацея от стремления генерировать хаос.
Документация в репозитории, при изменении она проходит ревью как обычный код с diffами, билдится в документационный проект и отдается потребителю.… не требует переключения контекста для разработчиков
О! То есть ПРОЦЕДУРА сделана органически удобной для сотрудников. Теперь — понятно, спасибо.
В MW есть плагин для ревью.
изменения положить в один коммит
Это означает, что сам по себе Диплодок работать не может, а выступает как надстройка над Гитхабом, да?
без внятного механизма актуализации и поиска.
Механизм поиска называется Elastic Search и прекрасно работает с MW.
Что значит ваш термин актуализация, я не понимаю и поэтому не могу ответить. Как движок занимается этой актуализацией?
Здорово, Markdown как язык продолжает жить и быть востребованным. Через пару лет, глядишь, и в ВК что-нибудь для разметки статей сделают :D
Полагаю, коллеги из ВК тоже не стоят на месте, как снаружи, так и изнутри. Мне сложно представить в наше время, что работа с любого рода документацией в больших компаниях происходит исключительно в ручных режимах - это не очень рационально.
Со своей стороны - буду только рад если ребята вовлекутся в развитие Diplodoc и принесут интересные фичи.
А как ваш проект соотносится с Яндекс wiki?
Это разные проекты и команды с точки зрения организации. Если спросите "А вы между собой разговариваете и чего-то придумываете/фиксите?" - да, конечно.
У Wiki и Diplodoc, как продуктов - немного разные задачи, постарался описать в комментарии выше.
Если спросите "что общего?" - вкратце, Wiki использует часть платформы Diplodoc (вот тут немного описано https://cloud.yandex.ru/docs/wiki/wysiwyg-create). Ну и справка Wiki, так же как и Облака - крутится на движке Diplodoc.
Все сервисы Yandex Cloud (включая Wiki и Tracker) для пользовательского контента используют Yandex Flavored Markdown, который используется в Diplodoc, и совместно его развивают.
Для пользователя это означает, в первую очередь, единый UX всех сервисов. Во-вторых, легкость перехода. Например, команда может по каким-то причинам сначала вести документацию в Wiki (для быстроты, потому что пока это не документация, а записки для себя и т.п.), а потом легко экспортировать её в Diplodoc при выходе в production.
Бонусом, знаю людей, которые пишут документацию в WIki WYSIWYG-ом, а потом экспортируют в Diplodoc. Но это, конечно, костыль. Думаю, в будущем визивиг в каком-то виде подружится с Diplodoc, тем более что он тоже в open source.
Хотелось бы иметь библиотеку на С для конвертации YFM в html. Такую как https://github.com/mity/md4c
Сделаете?
Сделать, наверное, можно. Это довольно большой объем работы, отсюда и вопрос - для какой цели?
Даже так - а почему текущее решение в виде transform+builder не устраивает? Вы куда-то статически/динамически либу линковать хотите?
Есть проекты, написанные на С, например cgit, где необходимо откидывать на экран md файлы преобразованные в html. В общем многие лююди пишут на С/C++, особенно для встроенных систем и md4c весьма популярна.
Честно скажу, мы не планировали в ближайшее время реализовывать подобную либу.
Нужно подумать и оценить запрос - насколько много и часто используется такой сценарий. Если будет большое количество и если будут контрибьюторы,в этом заинтересованные - попробуем поприоритизировать и помочь.
В любом случае - спасибо за принесенный кейс!
Diplodoc... Что то такое знакомое. Из молодости... Полчаса вспоминал... Diplom document. Так у нас назывались директории с документаций к дипломному проекту
Выглядит так, как будто вы изобрели собственный docusaurus. Смотрели ли вы в его сторону, можете написать чем ваше решение лучше? Ну кроме того, что оно ваше :)
Тут можно было бы подискутировать, кто и когда что изобрел, но в контексте open source это не очень релевантно.
Вообще, если говорить про похожесть решений и то, с чем можно сравнивать в пересечении функционала - их достаточно много.
Вы смотрите на Docusaurus, в предыдущих комментариях предлагали использовать MW, Hugo. Сюда можно добавить ReadTheDocs, GitBook, Swimm, Readocly, Stenography, Mintfly- поверьте, когда делали анализ перед выходом, много чего видели (порой, правда, странного). А если еще генераторы статики привнести (типа Jekyll, Hugo и иже с ними) - счет пойдет на сотни.
Вы абсолютно правы в том, что Diplodoc - это наше, собранное шишками, экспериментами и доказанное в повседневной работе.
Это одна из тех причин, почему мы вышли наружу - мы продвигаем идею Docs as Code и стараемся сделать инструментарий, максимально сфокусированный на этой концепции. Можете считать это, в какой-то степени, unix way - мы сконцентрированы на одной задаче и делаем ее хорошо.
Если по существу Вашего вопроса, я тут не буду юлить - Docusaurus это комбайн с кучей функционала, которого у нас нет. И некоторый мы умышленно не хотим включать. У комитета Docusaurus, видимо, такой вектор продуктового развития - больше и больше. Если помните, была такая штука Nero - сначала использовалась для записи дисков, потом в нее пихали больше и больше. А потом запись дисков стало commodity в операционных системах и продукт исчез с радаров. Надеюсь, что такого не произойдет у коллег.
Diplodoc - это, в первую очередь, технологическая платформа. Платформа для работы с документацией как с кодом. Вы можете заиспользовать ее целиком, а можете из этой платформы можете взять кусочки для решения своих задач.
Мы простые - и с точки зрения имплементации и с точки зрения работы с нами. Всей платформы или ее кусочков. И стремимся сделать ее использование еще проще.
Мы стабильные и быстрые - достаточные для хостинга справки большого Яндекса вовне и десятков тысяч людей внутри. Для маленьких проектов на пару страниц, для больших - в десятки тысяч.
Мы делаем фичи, которые необходимы в сценариях, о которых пользователи могут даже и не догадываться. Например, md2md renderer.
Мы рядом. Это значит, что мы не исчезнем, поскольку технология используется широко внутри Яндекса как минимум. Она выросла изнутри и останется.
Почему-то полгода назад я не нашел, что родительская компания использует для своей доки Docusaurus в проде.
Но в конечном итоге - все инструменты, перечисленные выше, конкурируют с нами, а мы - с ними. Как минимум, в части базового функционала.
Дальше уже начинаются нюансы, которые для Вас и организации могут быть киллерфичей (например, использование поиска в виде Elastic, а не Algolia), а для других - это вообще не аргумент.
Моя основная рекомендация тут - пробовать 2-3-4 разных тула под конкретные задачи и после этого принимать решение о внедрении или допиливании существующего.
Мы с удовольствием расскажем что у нас есть, чего у нас нет, планируем ли мы это реализовывать и подсаппортим в имплементации и ревью.
Мы рядом. Это значит, что мы не исчезнем, поскольку технология используется широко внутри Яндекса как минимум.
Пока существует Яндекс, существует ваша группа. Но что будет через тридцать, сорок, пятьдесят лет?
Если помните, была такая штука Nero — сначала использовалась для записи дисков, потом в нее пихали больше и больше. А потом запись дисков стало commodity в операционных системах и продукт исчез с радаров.
Причина несколько другая: потом запись дисков стало useless, а кому оно осталось полезным, те перешли на более узкопрофильные, частные инструменты.
Хм... 30-40-50 лет. Знаете, за последние 20 лет изменилось столько, что я бы не стал загадывать. Сам маркдаун появился в 2004, ютуб в 2005, гитхаб 2007. С точки зрения реализации программных систем (за некоторыми исключениями) - 20 лет это смена не одного поколения...
Тут Вы правы, я боюсь, что если организации не станет - не сможет поддерживать наша группа. Но это не значит, что сама система исчезнет - значит, до момента исчезновения организации надо или стандартом де-факто стать или взрастить коммьюнити, чтобы передавали знания из поколения в поколения, развивали и растили. К этому потенциально и стремимся - мы же вышли в open source.
А на старте взращивания и становления - работа совместно с большой компанией это плюс. Использование технологии в реальном окружении в той же компании - еще больший плюс. По меньшей мере - критический функционал, уязвимости и проблемы будут релизиться и фикситься с максимальным приоритетом.
Diplodoc — открытый набор инструментов для создания документации