Size: a a a
2019 December 13
Минутка UX-писательства. Вот это баннер про куки на culture.ru
А это тот же баннер на artlebedev.ru
Какой баннер вам больше по душе?
Анонимный опрос
Проголосовало: 3352019 December 18
TL;DR: чат DocOps за ноябрь
Лана Новикова собрала главное из чата DocOps-сообщества за ноябрь. Обсуждаемые темы, тезисы, полезные ссылки. Это очень круто, спасибо Лане.
https://teletype.in/@lananovikova/BJW5p0NAr
Лана Новикова собрала главное из чата DocOps-сообщества за ноябрь. Обсуждаемые темы, тезисы, полезные ссылки. Это очень круто, спасибо Лане.
https://teletype.in/@lananovikova/BJW5p0NAr
2019 December 26
Нотификации
Когда-то публикация доки в Plesk выглядела так: мы заходили по SSH на сервер, запускали команды и читали логи. Если что-то ломалось, копипастили логи разработчикам.
Потом всё это стал делать Jenkins. Поначалу мы запускали джобы вручную, потом подключили вебхуки к гит-репозиториям. Теперь коммиты в ветку мастер запускают публикацию. Но мы всё ещё смотрели прямо в Jenkins, как оно там, собралось уже или нет?
И вот под конец года я наконец добавил нотификации в Slack. Теперь в одном канале будет видна вся картина: что сегодня опубликовали, какие changelog'и обновились, где вдруг сломалась сборка. Кажется, не хватает только сообщений из вновь опубликованных коммитов.
А как вы мониторите публикацию доки? Расскажите в @docsascode.
Когда-то публикация доки в Plesk выглядела так: мы заходили по SSH на сервер, запускали команды и читали логи. Если что-то ломалось, копипастили логи разработчикам.
Потом всё это стал делать Jenkins. Поначалу мы запускали джобы вручную, потом подключили вебхуки к гит-репозиториям. Теперь коммиты в ветку мастер запускают публикацию. Но мы всё ещё смотрели прямо в Jenkins, как оно там, собралось уже или нет?
И вот под конец года я наконец добавил нотификации в Slack. Теперь в одном канале будет видна вся картина: что сегодня опубликовали, какие changelog'и обновились, где вдруг сломалась сборка. Кажется, не хватает только сообщений из вновь опубликованных коммитов.
А как вы мониторите публикацию доки? Расскажите в @docsascode.
2019 December 31
С Новым годом, друзья!
Записал небольшое поздравление для вас. :)
Записал небольшое поздравление для вас. :)
И ещё одно поздравление от нашего программного комитета: 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м ещё буду.
Давно хотел написать этот пост. Кажется, новогодняя ночь неплохо для него подходит. Я уже делал подборку чатов, а теперь напишу про каналы. Это не взаимный постинг — я им принципиально не занимаюсь. Просто перечислю всё, что сам читаю. В порядке возрастания подписчиков, чтобы эффект был равномернее. Если кого-то забыл, завтра проснусь и на свежую голову допишу.
Неожиданно, первым будет не канал, а блог на Дзене.
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м ещё буду.
2020 January 05
Переслано от Lana
Вы не ждали, а он появился, дайджест чатика за декабрь https://teletype.in/@lananovikova/rkQBPByeI
Давайте проверим. Кто ждал дайджест за декабрь? (https://t.me/docops/419)
Анонимный опрос
Проголосовало: 214docops
Чаты про документацию и управление знаниями.
Где задать вопрос, обсудить интересную тему или опубликовать вакансию? Давайте разберемся, а то я сам скоро запутаюсь.
Про документацию и инструментарий для неё, в частности про документацию как код — @docsascode, это чат канала DocOps.
Про документацию, правила и стиль, термины, работу с ГОСТ и госзаказчиками — @technicalwriters, чат сообщества технических писателей. Ещё туда можно кидать вакансии техписателей, с тегом #tw_wanted.
Управление знаниями, особенно в IT-компаниях — @KnowledgeConfTalks, чат конференции KnowledgeConf.
Управление знаниями в компаниях других отраслей — @kmrusnw. Там совсем другие масштабы и методы, но айтишечке всё равно есть чему поучиться у экспертов из кровавого энтерпрайза.
Перевод, локализация, интернационализация и в чем разница между этими словами — @localizer, чат переводчиков и всех причастных.
Тексты в интерфейсах — @meet_ux_txt, сообщество UX-писателей.
Есть отдельный чатик любителей AsciiDoctor — @asciidoctor.
Это такой легковесный язык разметки, альтернатива Markdown и reStructuredText.
Чаты стран и городов
Техписатели Украины @tw_ukraine. Там много специалистов по Madcap Flare, если что. Вакансии в Украине с хештегом #vacancy.
Сообщество Write the Docs в Минске @wtd_minsk.
Чат техписателей Перми @prm_techwriters.
Где задать вопрос, обсудить интересную тему или опубликовать вакансию? Давайте разберемся, а то я сам скоро запутаюсь.
Про документацию и инструментарий для неё, в частности про документацию как код — @docsascode, это чат канала DocOps.
Про документацию, правила и стиль, термины, работу с ГОСТ и госзаказчиками — @technicalwriters, чат сообщества технических писателей. Ещё туда можно кидать вакансии техписателей, с тегом #tw_wanted.
Управление знаниями, особенно в IT-компаниях — @KnowledgeConfTalks, чат конференции KnowledgeConf.
Управление знаниями в компаниях других отраслей — @kmrusnw. Там совсем другие масштабы и методы, но айтишечке всё равно есть чему поучиться у экспертов из кровавого энтерпрайза.
Перевод, локализация, интернационализация и в чем разница между этими словами — @localizer, чат переводчиков и всех причастных.
Тексты в интерфейсах — @meet_ux_txt, сообщество UX-писателей.
Есть отдельный чатик любителей AsciiDoctor — @asciidoctor.
Это такой легковесный язык разметки, альтернатива Markdown и reStructuredText.
Чаты стран и городов
Техписатели Украины @tw_ukraine. Там много специалистов по Madcap Flare, если что. Вакансии в Украине с хештегом #vacancy.
Сообщество Write the Docs в Минске @wtd_minsk.
Чат техписателей Перми @prm_techwriters.
Добавил в подборку три локальных чата: Украина, Минск, Пермь. Присоединяйтесь :)
2020 January 10
Контрастная тема в документации
Microsoft сделал в своей документации не только светлую и тёмную темы, но ещё и контрастную. Я впервые встречаю такое и это очень круто, потому что делает сайт доступным для людей с нарушениями зрения.
Вообще, у MS всегда было неплохо с accessibility (a11y, доступностью). Например, с незапамятных времён в Windows была экранная лупа, диктор и увеличенный вдвое интерфейс. Молодцы, ставят высокую планку для всей отрасли.
Microsoft сделал в своей документации не только светлую и тёмную темы, но ещё и контрастную. Я впервые встречаю такое и это очень круто, потому что делает сайт доступным для людей с нарушениями зрения.
Вообще, у MS всегда было неплохо с accessibility (a11y, доступностью). Например, с незапамятных времён в Windows была экранная лупа, диктор и увеличенный вдвое интерфейс. Молодцы, ставят высокую планку для всей отрасли.
2020 January 15
Лана шарит, читайте!
Переслано от Lana
Я тут собрала все известные мне способы публикации из разметки в конфлуэнс в статейку, https://habr.com/ru/post/483898/ это чуть больше, чем я рассказывала на митапчике, так как sphinxcontribbuilder обновился 3 января и стал поддерживать много классных плюшек, типа джира фильтров, мат формул, нумерованных заголовков и т.д.
2020 January 16
Ребята из Фланта рассказали, как собирают документацию с помощью werf. Это их инструмент для автоматизации сборки докер-образов. Отличный пример принципа "drink your own champagne".
https://habr.com/ru/company/flant/blog/478690/
https://habr.com/ru/company/flant/blog/478690/
2020 January 18
Мы сейчас на хакатоне Профунктора делаем инструмент для описания мокапов интерфейса текстом. Не точных прототипов, которые дизайнеры рисуют, а чисто в функциональном стиле. «Здесь поля ввода логина и пароля, потом кнопка "войти"». Короче, mockups as code.
Нам интересны мнения людей, которые рисуют такие мокапы для техзаданий и прочего. Наверняка среди моих читателей есть такие люди.
Сможете ответить на несколько вопросов?
Форма тут, пока только на английском, завтра переведу. https://forms.gle/ce1z4i4wYCk5oJs96
Нам интересны мнения людей, которые рисуют такие мокапы для техзаданий и прочего. Наверняка среди моих читателей есть такие люди.
Сможете ответить на несколько вопросов?
Форма тут, пока только на английском, завтра переведу. https://forms.gle/ce1z4i4wYCk5oJs96
Кто хочет научиться локализации в docs as code? У нас в проекте есть библиотека на JavaScript, сайт и документация на Sphinx. Потрогаете пару форматов данных для перевода и онлайн-сервис для совместной работы. Это опенсорс, можно добавить в портфолио.
Перевод не тупой, фактически мы переводим DSL (доменно-специфический язык программирования). Надо много думать и исследовать отзывы пользователей.
Ищу переводчиков с английского на другие европейские языки. Переводить нужно сейчас, хакатон кончится в воскресенье вечером (но проект будет жить и дальше).
Пишите @nick_volynkin, если у вас хороший уровень языка и вы готовы переводить прямо сейчас.
Перевод не тупой, фактически мы переводим DSL (доменно-специфический язык программирования). Надо много думать и исследовать отзывы пользователей.
Ищу переводчиков с английского на другие европейские языки. Переводить нужно сейчас, хакатон кончится в воскресенье вечером (но проект будет жить и дальше).
Пишите @nick_volynkin, если у вас хороший уровень языка и вы готовы переводить прямо сейчас.
2020 January 20
Смотрите, что у нас получилось: https://imagineui.github.io
Рисовалка мокапов из кода работает в браузере, есть несколько примеров и можно что-то новое задизайнить. Есть и CLI-приложение, пока что не упакованное, но можно собрать и запустить из кода, инструкция там же. Есть базовая документация на английском и русском.
Пробуйте, пишите фидбек, присылайте исходники своих мокапов :)
А ещё, если вам проект понравился, поставьте нам звезду на гитхабе: https://github.com/imagineui/imagineui
Рисовалка мокапов из кода работает в браузере, есть несколько примеров и можно что-то новое задизайнить. Есть и 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
2020 January 21
Ура, репозиторий ImagineUI набрал 50 звёзд! Сайт за два дня посетили больше 800 человек и мы получили 27 ответов на опросник.
Спасибо всем, кто про нас рассказал или репостнул:
@opensource_findings
@lovely_it_hell
@tech_b0lt_Genona
@count0_digest
@devpassion
За организацию хакатона спасибо @libmustdie.
Самое главное, спасибо команде. Вадим @vadkou затащил разработку тулзы, Наталья @natplatova сделала нам лендинг, Станислав @StanleyAppleseed перевёл доки на испанский.
А я впервые попробовал себя в роли, в которой мне доступны все технические и маркетинговые коммуникации. Не только документация, но и сайт, опросы, локализация, аналитика, блог. На очереди почтовая рассылка, интервью с пользователями, каналы фидбека и остальное.
Полным набором инструментов можно сделать гораздо больше, чем только одной документацией. Это воодушевляет.
Спасибо всем, кто про нас рассказал или репостнул:
@opensource_findings
@lovely_it_hell
@tech_b0lt_Genona
@count0_digest
@devpassion
За организацию хакатона спасибо @libmustdie.
Самое главное, спасибо команде. Вадим @vadkou затащил разработку тулзы, Наталья @natplatova сделала нам лендинг, Станислав @StanleyAppleseed перевёл доки на испанский.
А я впервые попробовал себя в роли, в которой мне доступны все технические и маркетинговые коммуникации. Не только документация, но и сайт, опросы, локализация, аналитика, блог. На очереди почтовая рассылка, интервью с пользователями, каналы фидбека и остальное.
Полным набором инструментов можно сделать гораздо больше, чем только одной документацией. Это воодушевляет.