DocOps

​​Только мне кажется, что тут всё перепутано? Метод 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

DocOps pinned «Ищу рассказчиков о провалах в IT. Мы с ребятами из конференции Russian Python Week делаем мини-конфу об ошибках и катастрофах в нашей любимой айтишечке. Идея и смысл такие: — Ошибки — это повод для изменений к лучшему, а не для наказаний и позора. (Blameless…»

​​Вебинар про документацию, 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

Обнаружил своего клона @nickvolynkin, юзернейм почти такой же и описание скопировано. Знайте, это не я, а какой-то самозванец. Денег не давайте, выступать не зовите. А меня зовите, я-то настоящий :)

О, сколько нам открытий чудных готовит... чтение документации.

Вадим Беляев пишет:
Сегодня я случайно решил почитать документацию по SQLite. Я офигел и прозрел. Если вкратце, то SQLite — это такой джаваскрипт в мире баз данных. Тред с весёлыми запросами в консоли
https://threadreaderapp.com/thread/1279522137754255360.html

Какие выводы тут можно сделать:
— Люди не сразу читают документацию, так что лучше бы интерфейс был сразу понятен и очевиден.
— Есть полезный формат статьи "Что необычного в технологии Х" или даже "Х — это <пример странной фигни> в мире <аналогов Х>". Если у вас в продукте есть такие неожиданно-непредсказуемые штуки, может быть полезным описать их в одном месте.

(ссылку нашёл в @rxd_txd)

​​Опрос про хостинг документации.

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

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

Автостопом по... PlantUML

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

https://crashedmind.github.io/PlantUMLHitchhikersGuide/

​​Краткое содержание в начале статьи — это добро.

В начале каждой статьи на сайте Nielsen Norman Group есть параграф с кратким содержанием статьи (summary). Это просто великолепно. Я хочу такой параграф в начале всех текстов в мире.

🗜 И вот ещё Ansible для самых маленьких - Deploying a static website with Ansible. Пошаговая инструкция как развернуть простой сайт на сервере с Nginx с помощью Ansible. #ansible #напочитать #nginx

Сразу и сайт с доками сделать, и Ansible потрогать.

После долгого перерыва Яндекс снова организует Мини-Гипéрбатон, митап про документацию и тексты. В этот раз тема — локализация, машинный перевод и краудсорсинг.

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

и второй:
— Как эффективно предсказывать и оценивать качество машинного и краудсорсингового перевода?
— Оно будет плохим.

И тем интереснее, что расскажут докладчики. Уверен, что ответы не будут капитанскими.

22 июля, онлайн, регистрируйтесь хоть сейчас.

Эволюция и маркетинговый отбор.

В эволюции видов есть половой отбор. Это такая штука, из-за которой появляются странные и даже вредные для выживания признаки вроде огромного павлиньего хвоста.

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

The SwaggerHub team
Steph from SmartBear
Patrick Londa from SmartBear

Кажется, пройдет ещё пара месяцев и следующий заголовок будет какой-то такой:

Alonzo the Magnificent from S...

Но я это письмо уже не получу, потому что только что случайно отписался. Просто не понял, от кого рассылка. Подумал, что очередной спам.

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