Каналы про документацию и управление знаниями.

Давно хотел написать этот пост. Кажется, новогодняя ночь неплохо для него подходит. Я уже делал подборку чатов, а теперь напишу про каналы. Это не взаимный постинг — я им принципиально не занимаюсь. Просто перечислю всё, что сам читаю. В порядке возрастания подписчиков, чтобы эффект был равномернее. Если кого-то забыл, завтра проснусь и на свежую голову допишу.

Неожиданно, первым будет не канал, а блог на Дзене.

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м ещё буду.

Обновление от 2021 года:

@gostdoc, Документалист.ГОСТ.

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

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

​​Контрастная тема в документации
Microsoft сделал в своей документации не только светлую и тёмную темы, но ещё и контрастную. Я впервые встречаю такое и это очень круто, потому что делает сайт доступным для людей с нарушениями зрения.

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

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

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

Ребята из Фланта рассказали, как собирают документацию с помощью werf. Это их инструмент для автоматизации сборки докер-образов. Отличный пример принципа "drink your own champagne".

https://habr.com/ru/company/flant/blog/478690/

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

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

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

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

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

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

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

​​Смотрите, что у нас получилось: 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: Subnoscription
    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

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

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

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

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

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

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

Используем 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://news.1rj.ru/str/manandthemachine/514.

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

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