DocOps

Конспект доклада Универсальная карта компетенций с 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

Ребята из Фланта рассказали, как собирают документацию с помощью werf. Это их инструмент для автоматизации сборки докер-образов. Отличный пример принципа "drink your own champagne". https://habr.com/ru/company/flant/blog/478690/

Я тут собрала все известные мне способы публикации из разметки в конфлуэнс в статейку, https://habr.com/ru/post/483898/ это чуть больше, чем я рассказывала на митапчике, так как sphinxcontribbuilder обновился 3 января и стал поддерживать много классных плюшек, типа джира фильтров, мат формул, нумерованных заголовков и т.д.

Лана шарит, читайте!

​​Контрастная тема в документации Microsoft сделал в своей документации не только светлую и тёмную темы, но ещё и контрастную. Я впервые встречаю такое и это очень круто, потому что делает сайт доступным для людей с нарушениями зрения. Вообще, у MS всегда было неплохо с accessibility (a11y, доступностью). Например, с незапамятных времён в Windows была экранная лупа, диктор и увеличенный вдвое интерфейс. Молодцы, ставят высокую планку для всей отрасли.

Добавил в подборку три локальных чата: Украина, Минск, Пермь. Присоединяйтесь :)

Вы не ждали, а он появился, дайджест чатика за декабрь https://teletype.in/@lananovikova/rkQBPByeI

Каналы про документацию и управление знаниями. Давно хотел написать этот пост. Кажется, новогодняя ночь неплохо для него подходит. Я уже делал подборку чатов, а теперь напишу про каналы. Это не взаимный постинг — я им принципиально не занимаюсь. Просто перечислю всё, что сам читаю. В порядке возрастания подписчиков, чтобы эффект был равномернее. Если кого-то забыл, завтра проснусь и на свежую голову допишу. Неожиданно, первым будет не канал, а блог на Дзене. IT-всячина глазами технического писателя (9 читателей). Станислав пишет нечасто, но зато там целые истории про работу техписателя. @getdocument (25). Автор периодически постит ссылки на хорошие статьи и видео, иногда пишет о собственном опыте обучения, например про документирование API и книгу Docs like Code. (Имя автора знаю, но в канале оно не указано, так что не пишу). @KnowledgeConfChannel (269). Канал KnowledgeConf — конференции про управление знаниями в IT. @shut_up_and_write Shut up and write (370). Мария хорошо пишет про документацию со стороны UX и пользовательских сценариев. В 2019м была серия постов со сравнением документации популярных продуктов сейчас и много лет назад. Особенно полезно, если вы пишете доки для не-разработчиков. @the_know_all The Know All — Управление знаниями в IT (373). Лана, с которой мы вместе работаем в ПК KnowledgeConf, ведёт канал про управление знаниями. Мой любимый пост — про Окно Джохари. @techwriters Techwriter's Daily (390). Анонимный автор или даже команда авторов внимательно следит за курсами и мероприятиями для техписателей, иногда пишет про инструменты и другие полезные штуки. Аноним, спасибо за репосты! @technical_writing Technical Writing 101 (718). Никита пишет про Markdown и генераторы статических сайтов, часто пробует новые инструменты, а ещё находит ссылки на дельные статьи на английском. Мне особенно понравились посты про диаграммы как код и линтер Vale. Ещё Никита — завсегдатай чата @docsascode. @lovely_it_hell Уютный адочек (843) Игорь, ещё один мой коллега по KnowledgeConf, пишет про управление разработкой в целом. Много постов про управление знаниями, онбординг сотрудников, рост и исследования. На случай, если это куда-нибудь репостнут, добавлю себя. @docops, DocOps (1796) Николай, пишу про документацию как код и другие практики DocOps. Пропагандирую само это слово и всё хорошее, что за ним стоит. Помогаю делать конференцию KnowledgeConf. Поддерживаю техписательское сообщество по мере сил. Раньше организовывал митапы про документацию и в 2020м ещё буду.

И ещё одно поздравление от нашего программного комитета: https://youtu.be/XWBkXfk6iZ0

С Новым годом, друзья! Записал небольшое поздравление для вас. :)

​​Нотификации Когда-то публикация доки в Plesk выглядела так: мы заходили по SSH на сервер, запускали команды и читали логи. Если что-то ломалось, копипастили логи разработчикам. Потом всё это стал делать Jenkins. Поначалу мы запускали джобы вручную, потом подключили вебхуки к гит-репозиториям. Теперь коммиты в ветку мастер запускают публикацию. Но мы всё ещё смотрели прямо в Jenkins, как оно там, собралось уже или нет? И вот под конец года я наконец добавил нотификации в Slack. Теперь в одном канале будет видна вся картина: что сегодня опубликовали, какие changelog'и обновились, где вдруг сломалась сборка. Кажется, не хватает только сообщений из вновь опубликованных коммитов. А как вы мониторите публикацию доки? Расскажите в @docsascode.

TL;DR: чат DocOps за ноябрь Лана Новикова собрала главное из чата DocOps-сообщества за ноябрь. Обсуждаемые темы, тезисы, полезные ссылки. Это очень круто, спасибо Лане. https://teletype.in/@lananovikova/BJW5p0NAr