​​Пока кто-нибудь только задумывается о переезде с допотопных CMS на docs-as-code, продвинутые ребята из Lisk переезжают с Markdown на AsciiDoc и Antora.

Хоть я и перетащил на reST пару десятков проектов, для меня в этой статье много полезного. Например, Lisk вместе со сменой инструмента переработали структуру доки. Их топологию можно использовать как «таблицу Менделеева»: про каждый сегмент подумать, а что из нашей документации сюда ложится? Как люди это найдут, как будут читать? А если ничего нет, не стоит ли написать?

Оказывается,​ топология документации, про которую я писал в прошлом посте, взята из статьи Daniele Procida What nobody tells you about documentation.

Есть и видео доклада по этой теме: https://www.youtube.com/watch?v=t4vKPhjcMZg

Похоже, что придумали это Daniele Procida и Tim Graham вместе. Вот упоминание аж из 2015 года, документация Django: https://github.com/django/django/commit/df3d5b1d73699b323aac377dffab039dca26c1e4

Спасибо @Aburnashev за подсказку.

Diagrams теперь поддерживает не только облачную инфраструктуру, но и on-premises. Красота!

Вот выйду из отпуска — пойду к нашим разработчикам пиарить этот инструмент.

Выводы к опросу постом выше:

https://t.me/oleg_log/2907

Лекция про DocOps на курсе Факторовича про техническую документацию в IT. Попробую дать определение этой штуке, которая уже два года висит в заголовке канала :)

Через 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