Используем Markdown для верстки HTML Email
https://pbpython.com/markdown-email.html

​​Из всех тем, о которых я мог бы сказать что-нибудь полезное, в книжку попали GitHub Wiki. 🤦‍♂️

(Docs like Code, второе издание, автор Anne Gentle, docslikecode.com)

​​Сегодня мои коллеги из KnowledgeConf пришли на конференцию TeamLeadConf. У них там стенд — участок Полиции Знаний. Если вы на конфе — приходите к ним и чистосердечно признавайтесь. :)

Конспект доклада Универсальная карта компетенций с TeamLeadConf 2020

Я сегодня на конференции для тимлидов и здесь тема управления знаниями актуальна, как никогда. Начинаем день с доклада Галины Головановой из Тинькофф, она рассказала, как они применили у себя популярную методику построения карты компетенций в команде.

Ссылка на конспект: https://github.com/lananovikova10/conspectus/blob/master/competence-matrix-tinkoff.md

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

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

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

Diagram as Code for prototyping cloud system architectures
https://github.com/mingrammer/diagrams

Люблю такое

Карен Товмасян пишет про отбор кандидатов:

Но допустим, есть ряд людей, которые шарят, знают и хорошо вписываются в команду. Если такой человек один - думать нечего, надо брать.
...
Если же таких несколько, то выбираю по следующим критерям (список построен случайным образом).
1.  Кто из кандидатов принесет с собой тот опыт, который отсутствует в команде
2.  Кто из кандидатов выглядит наиболее заинтересованным в работе
3.  Кто из кандидатов выглядит наиболее обучаемым

Новый человек не всегда может "поднять планку" команды, но если он дополнит ее компетенции - это уже победа.
...
Обучаемость не определяется никак, но ее можно проверить, задав вопрос по той теме, которую кандидат открыл для себя недавно.

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

Конечно, я это вырвал из контекста. Читайте плотностью, там три поста, начало здесь: https://t.me/manandthemachine/514.

А про знания в айтишных командах приходите поговорить на KnowledgeConf.

Если хотите поделиться своим опытом в докладе или хотя бы подозреваете, что вам есть, что сказать — пишите @nick_volynkin, обсудим. Лично я уверен, что у вас есть хорошие темы, так что отбросьте скромность и пишите. :)

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

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

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

Всё-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

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

RTFM!

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

Подкаст "Тимлид позвонит" об управлении знаниями

Поговорили с ребятами из SkyEng про хранение знаний в айти-компаниях, подходах к документированию и всяческих лайфхаках.
Я чуть больше рассказал про систему поиска и практику задавания вопросов, которые мы построили во "Фланте", а ведущие поделились своими историями.

52 минуты о реальной практике: https://www.youtube.com/watch?v=3X1SOZtVxcw

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

У конспектов появился сайт. Он пока что совсем простой и без домена, фичи будем добавлять по мере сил. :)
Последнее обновление — митап про документацию с недавнего 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 выпустил курс по техдокументации для инженеров. Он состоит из двух частей общей длительностью не больше восьми часов.

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