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

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