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

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

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

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

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

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

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

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

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

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

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

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

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

​​Пока кто-нибудь только задумывается о переезде с допотопных 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://www.tg-me.com/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