DocOps

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 и допиливание темы.

Подкаст "Тимлид позвонит" об управлении знаниями Поговорили с ребятами из SkyEng про хранение знаний в айти-компаниях, подходах к документированию и всяческих лайфхаках. Я чуть больше рассказал про систему поиска и практику задавания вопросов, которые мы построили во "Фланте", а ведущие поделились своими историями. 52 минуты о реальной практике: https://www.youtube.com/watch?v=3X1SOZtVxcw

Игорь Цупко, мой коллега из KnowledgeConf, рассказывает про управление знаниями.

Забавная история. Человек искал инструмент для управления зависимостями в Python, невнимательно прочитал доки к Poetry, в итоге написал свой велосипед и статью о нем на Хабре. В комментариях автора убедили, что Poetry решает его задачи. Он прочитал доки внимательно — и правда, решает. RTFM!

Всё-as-a-Code Мы привыкли, что артефакты для большинства стадии разработки ПО (SDLC) можно представлять в виде кода: тесты как код, инфраструктура как код, документация как код (@docops), архитектура как код, мокапы как код (https://imagineui.github.io/ru/). Потому что в таком случае к этим артефактам применимы все те же подходы, которые используются для кода: версионирование, ревью, автоматические проверки и т.д. Казалось, что требования к ПО были последним бастионом в этом движении, но с doorstop пал и этот бастион и теперь даже системные требования превратить в код. Каждое требование - отдельный файл в формате YAML, есть интеграция с Python. Кстати требования для самого инструмента описаны в виде требований doorstop - https://github.com/doorstop-dev/doorstop/tree/develop/reqs Презентация - https://speakerdeck.com/jacebrowning/doorstop-requirements-management-using-python-and-version-control

All you need is code, code, code. Code is all you need.

Дайджест чата за январь вам задолжала)) https://teletype.in/@lananovikova/siAoL2CS Месяц - огонь был к слову, столько полезного материала, ух

Читаем дайджест чата @docsascode.

Карен Товмасян пишет про отбор кандидатов: Но допустим, есть ряд людей, которые шарят, знают и хорошо вписываются в команду. Если такой человек один - думать нечего, надо брать. ... Если же таких несколько, то выбираю по следующим критерям (список построен случайным образом). 1. Кто из кандидатов принесет с собой тот опыт, который отсутствует в команде 2. Кто из кандидатов выглядит наиболее заинтересованным в работе 3. Кто из кандидатов выглядит наиболее обучаемым Новый человек не всегда может "поднять планку" команды, но если он дополнит ее компетенции - это уже победа. ... Обучаемость не определяется никак, но ее можно проверить, задав вопрос по той теме, которую кандидат открыл для себя недавно. Из трёх критериев два — про знания. Причем это не банальное "сколько человек знает", а скорее "кто будет полезнее для знаний и опыта всей команды". Конечно, я это вырвал из контекста. Читайте плотностью, там три поста, начало здесь: https://t.me/manandthemachine/514. А про знания в айтишных командах приходите поговорить на KnowledgeConf. Если хотите поделиться своим опытом в докладе или хотя бы подозреваете, что вам есть, что сказать — пишите @nick_volynkin, обсудим. Лично я уверен, что у вас есть хорошие темы, так что отбросьте скромность и пишите. :)

Diagram as Code for prototyping cloud system architectures https://github.com/mingrammer/diagrams Люблю такое

Кстати, если вы на конференции и что-то конспектируете, то пуллреквесты приветствуются. Вот шаблон, можно оттуда скопировать «шапку» с метаданными. https://github.com/docops-hq/conf/blob/master/content/teamleadconf/20/documentation_challenges.md

​​Сообщество Write the Docs тоже работает на своём стенде на TeamLeadConf. Только что Семён Факторович и Константин Валеев провели митап «Что делать, чтобы документация не болела». Держите конспект: docops-hq.github.io/conf/teamleadconf/20/documentation_challenges/

Полиция знаний продолжает работу! Сегодня в 16:30 по Мск будет конкурс-голосование за самое страшное преступление против знаний. Ссылку или опрос скину сюда.