Ищу рассказчиков о провалах в IT.

Мы с ребятами из конференции Russian Python Week делаем мини-конфу об ошибках и катастрофах в нашей любимой айтишечке. Идея и смысл такие:

— Ошибки — это повод для изменений к лучшему, а не для наказаний и позора. (Blameless, ага).
— Рассказывать об ошибках — это хорошо и ценно, порой куда ценнее, чем об успехах.
— Слушать про ошибки — интересно и увлекательно, а ещё это когда-нибудь спасёт вашу работу, проект и компанию.

Будет несколько историй о провалах, как они возникли, как с ними справились, и как их можно было бы предотвратить. Истории не менеджерские и не про бизнес, а чисто технические. Даже придумали жанры «технический детектив» и «технический триллер». Докладчикам поможем рассказать интересно и хардкорно.

Если вам есть, что рассказать, пишите мне, @nick_volynkin. Если сомневаетесь, тем более пишите, обсудим. :) Можно и сразу подать заявку, выбирайте там секцию FailPy, тогда заявка будет видна только программному комитету.

​​Вебинар про документацию, 22 июля (среда), 12:00 Мск.

Буквально завтра пройдет вебинар про документацию от сообщества Конвеерум (@konveerum). Будет два доклада:

— Как мы рисовали комиксы и что из этого получилось. (Сергей Кузин, Uniscan Research)

— Вам кажется, что с вашей документацией что-то не так? Вам не кажется. (Семён Факторович, documentat.io). Похоже, это будет повтор доклада с KnowledgeConf.

Регистрация: http://amp.gs/wkym

Быстрые результаты в управлении знаниями, 22 июля (среда), 14:30–16:00 Мск.

Мои коллеги из KnowledgeConf проводят мозговой штурм на тему «что быстро и недорого сделать в управлении знаниями, чтобы был результат и выгода для компании». Другими словами, с чего начать, если тема управления знаниями для вас совсем новая. Мне самому интересно, я пойду :)

Передаю слово Игорю Цупко (@lovely_it_hell):

Мы хотим сформулировать приёмы, которые можно внедрить просто договорившись, поменяв какую-то настройку в софте, написав инструкцию на два абзаца и т.п.. Приёмы, которые могут быть восприняты даже скорее как "хорошие идеи", но влекут за собой много позитивных последствий.

Ждём всех, кому не безразлична тема управления знаниями и кто хочет изменить что-то к лучшему в своей компании. Уверены, что идеи, которые мы сформулируем, помогут вам в вашей работе.

Регистрация: tsupko-tech.timepad.ru/event/1357069

Дайджест чата и результаты исследования.

Лана Новикова написала дайджест чата @docsascode за июнь. Там куча полезных ссылок, которые не попали в канал. https://teletype.in/@lananovikova/docops-june. Читайте и приходите в чат с вопросами, идеями и новостями.

Руслан Косолапов опубликовал итоги исследования про хостинг документации, о котором я недавно писал. Из интересного: респонденты либо не знают точные затраты на хостинг, либо уверены что они меньше $100 в месяц. А ещё, канал @docops — один из основных источников информации о хостинге документации :)

​​Хороших статей вам на выходные.

Настя Дмитриева из «Актива» начала серию статей про то, как в компании пишут пользовательскую документацию. Первая статья — про стоимость разработки документа и людей, которые участвуют в разработке.

Катя Носкова из Xsolla написала про онбординг технических писателей. По статье можно учиться онбордингу кого угодно, особенно если тема для вас совсем новая.

(Если вы не узнали, Xsolla — это те самые ребята в авангарде непрерывной локализации, которые внедрили Serge, когда это ещё не было мейнстримом.)

Архитекторы говорят про документацию сегодня в 20:00 Мск.

Сегодня вечером сообщество @it_arch будет обсуждать пользу и смысл документации в разработке архитектуры ПО:

— Как связаны между собой описание архитектуры и документация?
— Модели и диаграммы. Когда появится API архитектурного репозитория?
— Каким станет описание архитектуры к 2025 году?

Ссылка и все подробности в канале: https://t.me/it_arch/871

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

✔️ — в доке всё правильно: open делает копию, new редактирует оригинальную картинку.
❌ — в доке ошибка: open редактирует , new делает копию.

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

Чтобы не запутывать пользователя API, можно было бы дать методам имена, не связанные с их внутренней реализацией. Например, copy и modify.

Спасибо @dside_ru, что объяснил про конструктор.

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

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

📈 Высокой культуры пост

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

Пишет Игорь Цупко, мой единомышленник и соратник по KnowledgeConf:

Привет, коллеги!

Последний год мы с коллегами из KnowledgeConf занимаемся систематизацией и исследованиями подходов к менеджменту знаний и оформляем это всё в виде Прагматичного Гайда.

Мы выработали ряд походов и понимание того, как запустить или сделать более эффективным онбординг, выстроить документирование, обмен знаниями, сформулировать и распространить лучшие технологические практики внутри команды и компании. И мы хотим поделиться этим знанием с вами.

Если вы сейчас ищете подходы улучшить процессы управления знаниями — давайте пообщаемся и обменяемся опытом. Редакции гайда будет полезно узнать об актуальных для разработчиков проблемах, а вы, возможно, пополните свою копилку хорошими практическими идеями.

Чтобы принять участие — забейте временной слот (30-40 минут) через Calendly. По возможности укажите при забивании слота — какие проблемы менеджмента знаний для вас актуальны, чтобы нам не терять времени.

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

Добавил чат любителей AsciiDoctor — @asciidoctor.

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

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

Берегите себя, друзья. :)

Вторая мысль в отпуске: я работаю на одной работе 4 года и уже довольно неточно знаю, сколько я на самом деле стою. Пора это проверить. ;)

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

Гильдии в Plesk, Xsolla, Miro, РТ МИС и Сбере.

Ребята из разных компаний делятся опытом внутренних гильдий, то есть профессиональных сообществ. Только что сам начал смотреть, ничего не напишу в анонсе. Но гильдии — это отличная тема. У нас их аж несколько: QA, devops, frontend, backend, security, accessibility.

Судя по набору компаний, будет чертовски интересно. Рекомендую.

https://youtu.be/rCgXq1i4D9E

Максим Лапшин (Flussonic.com) написал подробный обзор @foliantdocs — комбайна для сборки и публикации документации в веб, PDF, конфлюенс и разные другие форматы. Доки Flussonic теперь собираются именно Фолиантом.

С разрешения автора публикую обзор здесь:

Я перетащил нашу документацию с самописной обертки вокруг ruby markdown на foliant.

Почему вообще возник вопрос о перезде?

* код писал я, причем очень давно и никакого желания дальше его развивать не было
* то, как я генерировал PDF с помощью ruby prawn было мягко говоря по-спартански

По сравнению с mkdocs и прочими фолиант подкупил интеграцией с пандоком, очень важная штука: бесплатно из коробки top-level поддержка PDF.

Чего мне не хватало из коробки в фолианте?

1. переименовывания результирующих файлов из их понятных имен вида live/publish.md в ужасный SEO-транслит potokovaya-peredacha/publikaciya
2. редиректов с человеческих unix-имен на транслит
3. возможности понять, какой урл будет у этой же страницы на другом языке для иконки языка
4. выгрузка кусков конфига из английской документации на диск для автотестов (мы тестируем документацию) и вставка их в русский вариант
5. выгрузка кусков документации в json для вставки их в админку нашего продукта


В целом всё это получилось решить плагинами, один из которых к mkdocs.

С чем возникли проблемы:

1. рубийный маркдаун существенно вольготнее относится к верске, чем питонячий. Пришлось много текста править
2. после рубийной Nokogiri, парсить HTML регекспами в питоне очень грустно. Очень не хватает API по объектному доступу к AST markdown
3. есть некоторая путаница между слоями метаданных фолианта и mkdocs. Вообще хотелось бы чтобы это не было разными вещами
4. процессоры фолианта разрешают падать и идти дальше. Реалии авторов фолианта такие, что им важнее собрать хоть что-то, чем собрать всё корректно. Мне наоборот — ворнинг уже повод упасть и не собирать документацию.
5. Пришлось написать немало кода, который подправлял плохую верстку в наших 3 миллионах символов (280 тыс слов)


Чего отдельно понравилось:

1. глобальное пространство имен анкоров. Ссылаться на уникальное по проекту имя секции — бесценно.
2. упаковка картинок и прочих ассетов в webpack-стиле, это важно
3. ну и вообще то, что люди решили его опенсорснуть и довести до отчуждаемого состояния. Это круто.