DocOps

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

Поговорили с ребятами из 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 по Мск будет конкурс-голосование за самое страшное преступление против знаний. Ссылку или опрос скину сюда.

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

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

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

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

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

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

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

Ура, репозиторий ImagineUI набрал 50 звёзд! Сайт за два дня посетили больше 800 человек и мы получили 27 ответов на опросник.

Спасибо всем, кто про нас рассказал или репостнул:
@opensource_findings
@lovely_it_hell
@tech_b0lt_Genona
@count0_digest
@devpassion

За организацию хакатона спасибо @libmustdie.

Самое главное, спасибо команде. Вадим @vadkou затащил разработку тулзы, Наталья @natplatova сделала нам лендинг, Станислав @StanleyAppleseed перевёл доки на испанский.

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

Полным набором инструментов можно сделать гораздо больше, чем только одной документацией. Это воодушевляет.

​​Смотрите, что у нас получилось: https://imagineui.github.io

Рисовалка мокапов из кода работает в браузере, есть несколько примеров и можно что-то новое задизайнить. Есть и CLI-приложение, пока что не упакованное, но можно собрать и запустить из кода, инструкция там же. Есть базовая документация на английском и русском.

Пробуйте, пишите фидбек, присылайте исходники своих мокапов :)

А ещё, если вам проект понравился, поставьте нам звезду на гитхабе: https://github.com/imagineui/imagineui

Mobile Page: "Landing"
Block: Navigation
    One row
    "ImagineUI"
    Link to Sandbox
    Link to GitHub
    Link to Docs
Main Block: Demo
    Header "ImagineUI"
    One row
    Image example source code
    Image example mockup
Block: Subscription
    Header Subscribe to our newsletter
    Input "full name"
    Input e-mail
    Button "Subscribe"
    "or try out the alpha-version:"
    One row
    Button Sandbox
    Button CLI

Кто хочет научиться локализации в docs as code? У нас в проекте есть библиотека на JavaScript, сайт и документация на Sphinx. Потрогаете пару форматов данных для перевода и онлайн-сервис для совместной работы. Это опенсорс, можно добавить в портфолио.

Перевод не тупой, фактически мы переводим DSL (доменно-специфический язык программирования). Надо много думать и исследовать отзывы пользователей.

Ищу переводчиков с английского на другие европейские языки. Переводить нужно сейчас, хакатон кончится в воскресенье вечером (но проект будет жить и дальше).

Пишите @nick_volynkin, если у вас хороший уровень языка и вы готовы переводить прямо сейчас.

Мы сейчас на хакатоне Профунктора делаем инструмент для описания мокапов интерфейса текстом. Не точных прототипов, которые дизайнеры рисуют, а чисто в функциональном стиле. «Здесь поля ввода логина и пароля, потом кнопка "войти"». Короче, mockups as code.

Нам интересны мнения людей, которые рисуют такие мокапы для техзаданий и прочего. Наверняка среди моих читателей есть такие люди.
Сможете ответить на несколько вопросов?

Форма тут, пока только на английском, завтра переведу. https://forms.gle/ce1z4i4wYCk5oJs96