В рубрике полезных инструментов для работы с документацией и воспроизводимостью исследований и работы с данными

Quatro [1] система с открытым кодом для подготовки научной и технической документации. Поддерживает интеграцию с Jupyter Notebook и создание dynamic documents, интерактивных публикаций, полезных в представлении многих научных результатов. Внутри Pandoc [2], умеет работать с Observable, Python, R, Julia и ещё много чего. Для полного счастья не хватает только web UI/GUI и удивительно что нет стартапа который бы подобное поверх Quatro не запилил, потому что движок также умеет делать книжки в ePub, PDF, MS Word.
В целом выглядит как удобная надстройка над Pandoc.

Курс Reproducible and Trustworthy Workflows for Data Science [3] о том как делать проекты для data science воспроизводимыми. Актуально для любых проектов на данных и аналитика без data science тоже, но тут всё подробно и конкретно. Курс полезный, стоит его пройти.

Ссылки:
[1] https://quarto.org/
[2] https://pandoc.org/
[3] https://ubc-dsci.github.io/reproducible-and-trustworthy-workflows-for-data-science/README.html

#openscience #opensource #documentation #datascience

Иногда полезно перечитывать отложенные ещё в прошлом году материалы и там есть интересные идеи.

Например, возможно, мало кто слышал про подход к разработке информационный систем Documentation-first или Docs First.

Это идея когда всё делается наоборот, а не как в привычном цикле. Вначале пишут документацию, потом по ней проектируют спецификации (API) и только потом пишут код.

То есть цикл не: код -> спецификация -> документация, а документация -> спецификация -> код

Об этом выступал Rahul Dighe на конференции ASC 2021 [1] с аргументами что разработчики - это тоже пользователи и заботится о них нужно ещё начиная со стадии проектирования.

Подход хоть и спорный, но интересный с точки зрения практики. Очень хочется какой-то живой пример где такой пример бы сработал.

А ещё он интересен с точки зрения самого подхода. Перевернуть цикл разработки с, казалось бы, привычной последовательности. А какие ещё процессы можно рассмотреть в той же модели? Так чтобы их можно было перевернуть ?

Ссылки:
[1] https://events.linuxfoundation.org/archive/2021/openapi-asc/program/schedule/

#API #ideas #documentation #docsfirst

Полезные ссылки про данные, технологии и не только:
- Governing data products using fitness functions [1] полезная статья с определением того что такое Data Product и как ими управлять, в первую очередь с архитектурной точки зрения.
- UIS Data Browser [2] новый каталог данных (статистики) ЮНЕСКО, данных немного, но есть API и массовая выгрузка.
- Why is language documentation still so terrible? [3] гневная статья где автор ругает все языки программирования кроме Rust. Претензий много и я с ним согласен и не только в отношении языков. Хорошую документацию на SDK или open source продукты встретишь нечасто.
- How We Made PostgreSQL Upserts 300x Faster on Compressed Data [4] про оптимизацию загрузки данных в PostgreSQL с помощью TimescaleDB, лично я не видел этот движок в работе, но для каких-то задач он может быть именно тем что нужно
- ImHex [5] шестнадцатеричный редактор с открытым кодом для реверс инжиниринга. На мой взгляд мало что заменит IDA Pro, но для задач не требующих хардкора и когда нет денег вполне себе полезный инструмент.

Ссылки:
[1] https://martinfowler.com/articles/fitness-functions-data-products.html#ArchitecturalCharacteristicsOfADataProduct
[2] https://databrowser.uis.unesco.org/
[3] https://walnut356.github.io/posts/language-documentation/
[4] https://www.timescale.com/blog/how-we-made-postgresql-upserts-300x-faster-on-compressed-data/
[5] https://github.com/WerWolv/ImHex

#opensource #data #datacatalogs #documentation #dbs

В рубрике как это устроено у них Docs [1] альтернатива Notion и Outline с открытым кодом, годится для совместного написания документов и командной работы над ними. Распространяется под лицензией MIT.

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

Проект является совместной инициативой DINUM (Межминистерского цифрового директората во Франции) и ZenDiS (Zentrum Digitale Souveränität), Центр Цифрового Суверенитета при Министерстве цифры Германии.

Иначе говоря - это совместный государственный франко-германский проект по созданию аналога Notion, а также сейчас у них идет онбординг цифровой команды пр-ва Нидерландов.

У ZenDIS ещё есть продукт OpenDesk [2] по замене офисного ПО для проектной и офисной работы. И внутри него совместное написание документов как раз основано на Docs.

OpenDesk довольно новый продукт, анонсированный в октябре 2024 года, но весьма активный и его код также общедоступен [3]

И, заодно, стоит добавить что сообщество пользователей продукта они строят не как все в Slack или Discord, а в Matrix [4]. Скажу честно, куда менее удобный мессенжер, но зато не относящийся к Big tech.

Ссылки:
[1] https://github.com/suitenumerique/docs
[2] https://opendesk.eu/
[3] https://gitlab.opencode.de/bmi/opendesk/info
[4] https://matrix.to/#/#docs-official:matrix.org

#opensource #documentation #notion

Наблюдаю взлет сервисов автоматического документирования публичных (и не публичных) репозиториев кода. Помимо хорошо известного DeepWiki есть, как минимум, Zread.ai и os.ninja, DeepWiki-Open, OpenDeepWiki, GitSummarize, DeepDocs и другие.

Некоторые из них даже выглядят симпатично, но ИМХО, в генерации документации для открытых репозиториев есть минус в том что это будет хорошо пока Github не сделает это как часть их подписки и тогда у всех сервисов которые сейчас есть и создаются останется востребованность только для кода вне Github'а или же придется очень сильно конкурировать за качество итоговой документации.

В общем, выглядит это всё это как интересный тренд, но с непонятным итогом потому что неявным маркетмейкером тут является Github (Microsoft) который быстро может убить все эти попытки, ну или как минимум сильно обесценить.

Но сама идея интересная и самое её очевидное применение legaltech. Потому что понятное структурированное и логичное изложение НПА по отдельности и по блокам это то что нехватает очень сильно. Мне, правда, самому легалтех не очень интересен, ибо я много матом ругаться и коньяка пить начинаю когда читаю законы. Но общая идея, ИМХО, понятна - в областях где есть объекты требующие подробного понятного изложения и где нет подобных маркетмейкеров подход через автогенерацию документацию в стиле вики будет оправдан

#thoughts #ai #documentation

Подборка ссылок про данные, технологии и не только:
- Blocking the Internet Archive Won’t Stop AI, But It Will Erase the Web’s Historical Record заметка в EFF о том что New York Times начали блокировать Интернет Архив поскольку опасаются что через него ИИ компании получат доступ к материалам издания. Подробнее на сайте NiemanLab и с упоминанием других изданий. Издателям не нравится что у Интернет Архива есть открытое API, а смысл публикаций в том что теперь они де-факто создают ситуацию когда их материалы не будут сохранены.
- Snowlake уволили всю команду документирования для тех кто не слышал о них - это компания одна из лидеров облачных дата платформ, и вот они пошли по пути полной замены всего подразделения документирования на ИИ. К чему это приведет скоро узнаем, однако тенденция эта не нова и новости про большие сокращения команд документирования проходили и ранее. Такими темпами скоро профессия технического писателя вымрет и заменится на профессию Developer experience engineer (DEE) которая может и должна включать коммуникацию с пользователями.
- Open Technology Research анонсированная глобальная платформа помощи исследователям создаваемая партнерством Open Knowledge Foundation, Open Source Initiative и OpenForum Europe. Интересное - акцент на открытой инфраструктуре. Но смущает отсутствие в инициаторах организаций выделяющих средства и самих исследовательских центров. Такой проект был бы логичнее от университетского консорциума или от консорциума доноров исследовательских проектов. А участие 3-х даже и уважаемых НКО про открытость не выглядит чем-то устойчивым.

#opensource #digitalpreservation #webarchives #documentation

В продолжение предыдущих размышлений про LLM модели и их применение меня всё чаще посещает что среди основанных на ИИ (LLM) инструментов пока нет (мало) инструментов для создания документации.

Например, для дизайна есть Claude Design и Open Design, оба довольно продвинутые инструменты. А для документации есть только онлайн платформы вроде Mintlify или Notion в которые встроена генерация текстов с помощью ИИ, но это делает тебя зависимым от этой платформы.

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

У меня есть личное предположение что тут может быть отдельный инструмент вроде того же Open Design, но для документации. Способный создавать контент по четким структурным шаблонам под разные платформы, продукты и так далее. Под Docusaurus, под Mkdocs, интегрированный с Mintlify и другими облачными провайдерами и так далее. Использующий ИИ также как это делает Open Design.

В принципе Open Design для меня пример сфокусированного продукта адаптируемого под конкретные задачи достаточно гибкого в вариантах подключения LLM для решения задач.

Что было бы важно в таком продукте:
1. Уметь создавать документацию под разные задачи в разных форматах - разные вики, PDF, MS Word и тд. Базово в Markdown со сборкой в нужный формат при необходимости.
2. Уметь оценивать автоматически качество документации по полноте и другим критериям.
3. Уметь формировать документацию по полученным вводным: начальным материалам, промптам, предоставленны документам, изображениям, коду и так далее
4. Уметь работать по шаблонам в зависимости от того на что документация создается: SaaS продукт, настольное приложение, клиентское приложение, дата продукт и тд.

Наверняка тут можно еще немало чего добавить.

#thoughts #documentation #aiagents

Добавлю ещё некоторое количество рефлексии по использовании LLM и ИИ агентов для создания базы знаний.

1. После некоторого числа экспериментов действительно Kimi K3 можно сравнить с последними моделями OpenAI и Anthropic. Созданные ей карточки в базе знаний куда более полные чем, к примеру, созданные с помощью GLM-5.2 или моделями попроще. Это важно поскольку существенно удешевляет процесс.
2. По наблюдениям наиболее эффективен двухэтапный процесс с human-in-the-loop. Вначале делать промпт на создание промпта, далее, делать его ревью и редактировать, при необходимости. и следующим шагом уже полученный промпт отдавать LLM. Первый этап можно делать и моделью попроще вроде той же GLM-5.2, а второй куда лучше отрабатывает уже более продвинутая модель. По сути это путь двухэтапного анализа поскольку при формировании комплексного промпта модель делает предварительный анализ объекта документирования.
3. Главный недостаток такого подхода в том что он существенно удлиняет процесс подготовки базы знаний, примерно в 2-3 раза и дублирует многие шаги потому что и, на предварительном анализа, и на финальном, идёт обращение к одним и тем же объектам. Например, если на вход поступает какой-то раздел сайта с набором тематических документов, то они скачиваются дважды. Может быть на стадии подготовки промпта не все, но тем не менее когда качество результата важнее скорости это лучший подход.
4. Что хорошо - это работает с любыми цифровыми объектами. Сайтами, датасетами, документами и коллекциями документов, API, текстами в иной форме, базами данных и так далее. Например, если бы я хотел не просто собрать базу данных межгосударственных организаций, но и сделать базу знаний по ним, то я сейчас вполне понимаю как это можно организовать структурно и технически. (оговорюсь - планов создавать такую базу знаний у меня пока нет).

#thoughts #ai #documentation

В продолжение про обновление internacia-db, вот немного фактов про страны и межгосударственные структуры:
- членами ООН является 193 страны, коды ISO (ISO 3166-1) присвоены 249 странам и территориям, в internacia-db всего 256 стран и территорий. разница в цифрах происходит от того что в internacia-db включены 7 территорий с оспариваемым статусом действующие и устаревшие. Это Косово, Абхазия, Южная Осетия, Приднестровье, Арцах, Нидерландские Антилы, Нормандские острова.
- возможно Нидерландские Антилы и Нормадские острова надо будет убрать из этого списка поскольку они де-факто разделены на несколько зависимых территорий у которых есть присвоенные ISO коды
- единственной страной которая независима и не член ООН является Ватикан. У Ватикана в ООН статус организации наблюдателя, это в internacia-db не фиксируется, тут только про страны. Но вообще Ватикан входит в 40 межгосударственных структур упомянутых в internacia-db
- с марта 2022 года формально РФ вышла из 3-х организаций: European University Association, European Court of Human Rights и International Council for the Exploration of the Sea. Во многих других её участие заморожено, но формально выхода или исключения нет поэтому простым запросом все случаи пока не отследить
- наиболее широко в межгосударственных структурах присутствуют Франция, Великобритания, Германия, Италия и США. Наименее - Северная Корея.
- если посмотреть на связи стран ОЭСР со всеми другими странами не входящими в эту межгосударственную структуру, то окажется что через соглашения они тесно связаны с Китаем, Россией и Индией и наименее всего с Северной Кореей
- из всех оспариваемых территорий Косово наиболее представлено в межгосударственных структурах и входит как страна во многие европейские соглашения, объединения и тд.

В документации есть множество примеров того как это и другие знания можно получить делая запросы к базе в DuckDB. Можно было бы показать еще больше разного интересного если свести эту базу с базой показателей стран и с базой международной торговли. Но это уже несколько за пределами этого репозитория референсных данных.

#opendata #datasets #documentation #dateno