DocOps

У меня тут заканчивается второй день отпуска, и я постепенно начинаю понимать, что отпуск стоило взять 1) гораздо раньше и 2) на гораздо больший срок, может быть, на месяц. Берегите себя, друзья. :)

Добавил чат любителей AsciiDoctor — @asciidoctor. AsciiDoctor — это ещё один легковесный язык разметки и генератор документации для него. Язык разметки похож на reStructuredText: выразительный, семантический но сложнее и менее популярный, чем Markdown. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

Я сам записался, между прочим. И вам рекомендую.

Пишет Игорь Цупко, мой единомышленник и соратник по KnowledgeConf: Привет, коллеги! Последний год мы с коллегами из KnowledgeConf занимаемся систематизацией и исследованиями подходов к менеджменту знаний и оформляем это всё в виде Прагматичного Гайда. Мы выработали ряд походов и понимание того, как запустить или сделать более эффективным онбординг, выстроить документирование, обмен знаниями, сформулировать и распространить лучшие технологические практики внутри команды и компании. И мы хотим поделиться этим знанием с вами. Если вы сейчас ищете подходы улучшить процессы управления знаниями — давайте пообщаемся и обменяемся опытом. Редакции гайда будет полезно узнать об актуальных для разработчиков проблемах, а вы, возможно, пополните свою копилку хорошими практическими идеями. Чтобы принять участие — забейте временной слот (30-40 минут) через Calendly. По возможности укажите при забивании слота — какие проблемы менеджмента знаний для вас актуальны, чтобы нам не терять времени.

📈 Высокой культуры пост Если вы хотите привнести что-то новое в компанию — вы всегда будете сталкиваться с сопротивлением. Одним из них может быть сказка про якобы уже существующую "высокую культуру", которой нет на самом деле. Некоторые топ-менеджеры, с которыми вам предстоит общаться, к месту и не к месту включают режим защиты своих решений, своего кода и своего наследия — даже не вникая в то, что вы им говорите. При этом на практике свою "высокую культуру" применить они не способны и их собственное поведение идёт полностью в разрез с декларируемым. Вам говорят про открытость — но цели и причины остаются в головах. Вам говорят про agile и гибкость — но жить нужно по заранее определённому плану и сбор обратной связи игнорируется. Вам говорят про инновации и идеи — но каждая секунда времени должна трекаться в задачи. Вам говорят про высокую культуру обмена знаниями — но запрещены попытки формулировать best practice. Подобный абсурд смешно звучит тогда, когда вы его осознали, но если у вас не так много опыта — легко поверить рассказам про высокую культуру на серьёзных щах. Старайтесь избегать дутых щёк в себе и окружающих, смотрите вокруг и задавайте неудобные вопросы.

Можно так, но можно и проще: git fetch --prune. https://t.me/itgram_channel/433

Следующая задача — вытащить документацию из кода. https://twitter.com/sigsergv/status/1293738764658003970

Тоня шарит! Мне тоже помогает такое. https://t.me/Editors_cave/158

Вот что мы выяснили о предыдущем посте: — В доке ошибки нет, она верно описывает API. — Выбор названий методов в API очень спорный. Можно ожидать, что open откроет на редактирование, а new сделает копию. Можно понять иначе: open только откроет картинку и не будет её редактировать. — Причина такого выбора может быть в том, что new — это метод-конструктор. Он задаёт поведение по умолчанию. Чтобы не запутывать пользователя API, можно было бы дать методам имена, не связанные с их внутренней реализацией. Например, copy и modify. Спасибо @dside_ru, что объяснил про конструктор.

​​Только мне кажется, что тут всё перепутано? Метод open же должен открывать существующий файл, а new — делать новый. Или всё правильно? ✔️ — в доке всё правильно: open делает копию, new редактирует оригинальную картинку. ❌ — в доке ошибка: open редактирует , new делает копию.

Архитекторы говорят про документацию сегодня в 20:00 Мск. Сегодня вечером сообщество @it_arch будет обсуждать пользу и смысл документации в разработке архитектуры ПО: — Как связаны между собой описание архитектуры и документация? — Модели и диаграммы. Когда появится API архитектурного репозитория? — Каким станет описание архитектуры к 2025 году? Ссылка и все подробности в канале: https://t.me/it_arch/871

​​Хороших статей вам на выходные. Настя Дмитриева из «Актива» начала серию статей про то, как в компании пишут пользовательскую документацию. Первая статья — про стоимость разработки документа и людей, которые участвуют в разработке. Катя Носкова из Xsolla написала про онбординг технических писателей. По статье можно учиться онбордингу кого угодно, особенно если тема для вас совсем новая. (Если вы не узнали, Xsolla — это те самые ребята в авангарде непрерывной локализации, которые внедрили Serge, когда это ещё не было мейнстримом.)

Дайджест чата и результаты исследования. Лана Новикова написала дайджест чата @docsascode за июнь. Там куча полезных ссылок, которые не попали в канал. https://teletype.in/@lananovikova/docops-june. Читайте и приходите в чат с вопросами, идеями и новостями. Руслан Косолапов опубликовал итоги исследования про хостинг документации, о котором я недавно писал. Из интересного: респонденты либо не знают точные затраты на хостинг, либо уверены что они меньше $100 в месяц. А ещё, канал @docops — один из основных источников информации о хостинге документации :)

Быстрые результаты в управлении знаниями, 22 июля (среда), 14:30–16:00 Мск. Мои коллеги из KnowledgeConf проводят мозговой штурм на тему «что быстро и недорого сделать в управлении знаниями, чтобы был результат и выгода для компании». Другими словами, с чего начать, если тема управления знаниями для вас совсем новая. Мне самому интересно, я пойду :) Передаю слово Игорю Цупко (@lovely_it_hell): Мы хотим сформулировать приёмы, которые можно внедрить просто договорившись, поменяв какую-то настройку в софте, написав инструкцию на два абзаца и т.п.. Приёмы, которые могут быть восприняты даже скорее как "хорошие идеи", но влекут за собой много позитивных последствий. Ждём всех, кому не безразлична тема управления знаниями и кто хочет изменить что-то к лучшему в своей компании. Уверены, что идеи, которые мы сформулируем, помогут вам в вашей работе. Регистрация: tsupko-tech.timepad.ru/event/1357069

​​Вебинар про документацию, 22 июля (среда), 12:00 Мск. Буквально завтра пройдет вебинар про документацию от сообщества Конвеерум (@konveerum). Будет два доклада: — Как мы рисовали комиксы и что из этого получилось. (Сергей Кузин, Uniscan Research) — Вам кажется, что с вашей документацией что-то не так? Вам не кажется. (Семён Факторович, documentat.io). Похоже, это будет повтор доклада с KnowledgeConf. Регистрация: http://amp.gs/wkym

Ищу рассказчиков о провалах в IT. Мы с ребятами из конференции Russian Python Week делаем мини-конфу об ошибках и катастрофах в нашей любимой айтишечке. Идея и смысл такие: — Ошибки — это повод для изменений к лучшему, а не для наказаний и позора. (Blameless, ага). — Рассказывать об ошибках — это хорошо и ценно, порой куда ценнее, чем об успехах. — Слушать про ошибки — интересно и увлекательно, а ещё это когда-нибудь спасёт вашу работу, проект и компанию. Будет несколько историй о провалах, как они возникли, как с ними справились, и как их можно было бы предотвратить. Истории не менеджерские и не про бизнес, а чисто технические. Даже придумали жанры «технический детектив» и «технический триллер». Докладчикам поможем рассказать интересно и хардкорно. Если вам есть, что рассказать, пишите мне, @nick_volynkin. Если сомневаетесь, тем более пишите, обсудим. :) Можно и сразу подать заявку, выбирайте там секцию FailPy, тогда заявка будет видна только программному комитету.

​​Будет легче, если сначала прочитаете... В начале статьи бывает полезно написать о предусловиях для чтения. Что читатель должен заранее сделать или прочитать, чтобы понять эту статью? Например, в статье про настройку X можно дать ссылку на установку этого X. Так читатель не потеряется и сначала вернётся к установке, если ещё не сделал её. Встретил отличный пример такой ссылки в доке Google Search Console: «This report is much easier to understand if you have read how Google Search works first.» Это так душевно звучит, с заботой о читателе.

Раздают книжку Developer, Advocate! Developer, Advocate! — книга о сообществах разработчиков, технопиаре, developer relations и всём таком. Компания Azul наняла автора книги Geertjan Wielenga и по такому случаю бесплатно раздаёт электронную версию книги. Конечно, в обмен на подписку. :)

Видео опубликовали. Напоминаю: на TechLeadConf рассказывали про инструменты для документации, с фокусом на доки от инженеров и для инженеров. Документирование кода, диаграммы и схемы, публикация в Confluence, вот это всё. Костя Валеев рассказал про Foliant, Семён Факторович — про Pandoc, а я про Sphinx. https://youtu.be/4qv0YNtuRlE