Минутка UX-писательства. Вот это баннер про куки на culture.ru

А это тот же баннер на artlebedev.ru

TL;DR: чат DocOps за ноябрь

Лана Новикова собрала главное из чата DocOps-сообщества за ноябрь. Обсуждаемые темы, тезисы, полезные ссылки. Это очень круто, спасибо Лане.

https://teletype.in/@lananovikova/BJW5p0NAr

​​Нотификации

Когда-то публикация доки в Plesk выглядела так: мы заходили по SSH на сервер, запускали команды и читали логи. Если что-то ломалось, копипастили логи разработчикам.

Потом всё это стал делать Jenkins. Поначалу мы запускали джобы вручную, потом подключили вебхуки к гит-репозиториям. Теперь коммиты в ветку мастер запускают публикацию. Но мы всё ещё смотрели прямо в Jenkins, как оно там, собралось уже или нет?

И вот под конец года я наконец добавил нотификации в Slack. Теперь в одном канале будет видна вся картина: что сегодня опубликовали, какие changelog'и обновились, где вдруг сломалась сборка. Кажется, не хватает только сообщений из вновь опубликованных коммитов.

А как вы мониторите публикацию доки? Расскажите в @docsascode.

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

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

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

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

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

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: 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

Ура, репозиторий 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