DocOps

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

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

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

​​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

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

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

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

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

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

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

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

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

https://t.me/oleg_log/2907

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

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

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

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

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

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

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

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

Курс по документации для инженеров.
Google выпустил курс по техдокументации для инженеров. Он состоит из двух частей общей длительностью не больше восьми часов.

Вот и решился вопрос, чем заняться на длинных выходных. :)

Читатель @ejiek подсказал ещё один пример документации прямо в месте ошибки — язык Rust.

Команда rustup docs --book показывает общую документацию языка Rust.

Все ошибки содержат краткое описание и заканчиваются номером ошибки:

For more information about this error, try rustc --explain E0271.

Команда rustc --explain E0271 показывает справку по ошибке и помогает её исправить.

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

Хороший пример: доки по синтаксису языка Elm принесли в сообщения об ошибках в синтаксисе. Теперь эти сообщения помогают изучить синтаксис и исправить ошибку.

Сайт с конспектами.

У конспектов появился сайт. Он пока что совсем простой и без домена, фичи будем добавлять по мере сил. :)
Последнее обновление — митап про документацию с недавнего TeamLeadConf.

Конспекты сгруппированы по тегам конференций и сообществ:
— Aletheia Business,
— DevOpsConf,
— DevRelConf (про технопиар и developer relations),
— FrontEndConf,
— Highload++,
— KnowledgeConf про управление знаниями в IT,
— MoscowPythonConf++,
— QualityConf,
— Siberian Comminity Orgs — орги IT-сообществ Сибири.

Спасибо всем двенадцати контрибьюторам конспектов и отдельно @natplatova за переезд на Hugo и допиливание темы.