Через 15 минут подключайтесь к лекции @Nick_Volynkin о DocOps!

Введение в DocOps (Николай Волынкин, Plesk) https://youtu.be/1CuMeMYwtbg

Костя Валеев, контрибьютор проекта Foliant, рассказывает про построение инфраструктуры для docs-as-code. Трансляция через 10 минут, подключайтесь: https://youtu.be/6CKVodl2YcA

​​KnowledgeConf прошла, подводим итоги. Ребята из нашего программного комитета дадут интервью Владимиру Лещенко сегодня вечером: https://www.youtube.com/channel/UCWjbphptoLgEyUWKUpaiWRA

Если вы не знакомы, Владимир — известный эксперт по управлению знаниями и автор Ютуб-канала. Рекомендую, там много хороших интервью.

Не всё понял, но выглядит интересно.

​​Great Expectations: Always know what to expect from your data.

Great Expectations helps data teams eliminate pipeline debt, through data testing, documentation, and profiling.

Software developers have long known that testing and documentation are essential for managing complex codebases. Great Expectations brings the same confidence, integrity, and acceleration to data science and data engineering teams.

See Down with Pipeline Debt! for an introduction to the philosophy of pipeline testing: https://medium.com/@expectgreatdata/down-with-pipeline-debt-introducing-great-expectations-862ddc46782a

Key features:
- Expectations or assertions for data. They are the workhorse abstraction in Great Expectations, covering all kinds of common data issues
- Batteries-included data validation
- Tests are docs and docs are tests: many data teams struggle to maintain up-to-date data documentation. Great Expectations solves this problem by rendering Expectations directly into clean, human-readable documentation
- Automated data profiling: wouldn't it be great if your tests could write themselves? Run your data through one of Great Expectations' data profilers and it will automatically generate Expectations and data documentation
- Pluggable and extensible

https://github.com/great-expectations/great_expectations

#python #ds #docops

Добавил сообщество UX-писателей @meet_ux_txt.

Мы с коллегами сегодня рассказывали на TechLeadConf про инструменты для публикации доки: Sphinx, Foliant и Pandoc. Записи пока нет, но мы могли бы повторить для широкой аудитории. Скажите, а про что вам было бы интересно послушать и задать вопросы?

Если вашего варианта нет, пишите в @docsascode

Эволюция и маркетинговый отбор.

В эволюции видов есть половой отбор. Это такая штука, из-за которой появляются странные и даже вредные для выживания признаки вроде огромного павлиньего хвоста.

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

The SwaggerHub team
Steph from SmartBear
Patrick Londa from SmartBear

Кажется, пройдет ещё пара месяцев и следующий заголовок будет какой-то такой:

Alonzo the Magnificent from S...

Но я это письмо уже не получу, потому что только что случайно отписался. Просто не понял, от кого рассылка. Подумал, что очередной спам.

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

После долгого перерыва Яндекс снова организует Мини-Гипéрбатон, митап про документацию и тексты. В этот раз тема — локализация, машинный перевод и краудсорсинг.

Темы докладов в этот раз кажутся очевидными...
— Как масштабировать тестирование локализации с помощью краудсорсинга?
— Ну, с помощью краудсорсинга.

и второй:
— Как эффективно предсказывать и оценивать качество машинного и краудсорсингового перевода?
— Оно будет плохим.

И тем интереснее, что расскажут докладчики. Уверен, что ответы не будут капитанскими.

22 июля, онлайн, регистрируйтесь хоть сейчас.

Сразу и сайт с доками сделать, и Ansible потрогать.

🗜 И вот ещё Ansible для самых маленьких - Deploying a static website with Ansible. Пошаговая инструкция как развернуть простой сайт на сервере с Nginx с помощью Ansible. #ansible #напочитать #nginx

​​Краткое содержание в начале статьи — это добро.

В начале каждой статьи на сайте Nielsen Norman Group есть параграф с кратким содержанием статьи (summary). Это просто великолепно. Я хочу такой параграф в начале всех текстов в мире.

Автостопом по... PlantUML

Руководство по PlantUML, библиотеке для рисования диаграмм кодом. Все примеры — про диаграммы сетей и архитектур приложений, что делает курс оптимальным для разработчиков и сетевых инженеров, но не очень подходящим для бизнес-аналитиков.

https://crashedmind.github.io/PlantUMLHitchhikersGuide/

​​Опрос про хостинг документации.

Мои знакомые делают инструмент для хостинга небольших сайтов, в том числе документации. Судя по рассказам, там будет автоматизирована куча важных штук, которые я бы не хотел делать вручную.

Мы вместе составили небольшой опросник про то, как хостятся документационные проекты. Пожалуйста, расскажите о своём опыте, там на 5-10 минут. С теми, кто оставит почту, обещают поделиться результатами опроса и демкой инструмента.

О, сколько нам открытий чудных готовит... чтение документации.

Вадим Беляев пишет:
Сегодня я случайно решил почитать документацию по SQLite. Я офигел и прозрел. Если вкратце, то SQLite — это такой джаваскрипт в мире баз данных. Тред с весёлыми запросами в консоли
https://threadreaderapp.com/thread/1279522137754255360.html

Какие выводы тут можно сделать:
— Люди не сразу читают документацию, так что лучше бы интерфейс был сразу понятен и очевиден.
— Есть полезный формат статьи "Что необычного в технологии Х" или даже "Х — это <пример странной фигни> в мире <аналогов Х>". Если у вас в продукте есть такие неожиданно-непредсказуемые штуки, может быть полезным описать их в одном месте.

(ссылку нашёл в @rxd_txd)

Обнаружил своего клона @nickvolynkin, юзернейм почти такой же и описание скопировано. Знайте, это не я, а какой-то самозванец. Денег не давайте, выступать не зовите. А меня зовите, я-то настоящий :)

Видео опубликовали. Напоминаю: на TechLeadConf рассказывали про инструменты для документации, с фокусом на доки от инженеров и для инженеров. Документирование кода, диаграммы и схемы, публикация в Confluence, вот это всё. Костя Валеев рассказал про Foliant, Семён Факторович — про Pandoc, а я про Sphinx.

https://youtu.be/4qv0YNtuRlE

Раздают книжку Developer, Advocate!

Developer, Advocate! — книга о сообществах разработчиков, технопиаре, developer relations и всём таком. Компания Azul наняла автора книги Geertjan Wielenga и по такому случаю бесплатно раздаёт электронную версию книги. Конечно, в обмен на подписку. :)

​​Будет легче, если сначала прочитаете...

В начале статьи бывает полезно написать о предусловиях для чтения. Что читатель должен заранее сделать или прочитать, чтобы понять эту статью? Например, в статье про настройку X можно дать ссылку на установку этого X. Так читатель не потеряется и сначала вернётся к установке, если ещё не сделал её.

Встретил отличный пример такой ссылки в доке Google Search Console:
«This report is much easier to understand if you have read how Google Search works first.»

Это так душевно звучит, с заботой о читателе.