Size: a a a

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

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

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

https://crashedmind.github.io/PlantUMLHitchhikersGuide/
источник
2020 July 08
DocOps
​​Опрос про хостинг документации.

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

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

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

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

(ссылку нашёл в @rxd_txd)
источник
DocOps
Обнаружил своего клона @nickvolynkin, юзернейм почти такой же и описание скопировано. Знайте, это не я, а какой-то самозванец. Денег не давайте, выступать не зовите. А меня зовите, я-то настоящий :)
источник
2020 July 13
DocOps
docops
Мы с коллегами сегодня рассказывали на TechLeadConf про инструменты для публикации доки: Sphinx, Foliant и Pandoc. Записи пока нет, но мы могли бы повторить для широкой аудитории. Скажите, а про что вам было бы интересно послушать и задать вопросы?

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

https://youtu.be/4qv0YNtuRlE
источник
2020 July 14
DocOps
Раздают книжку Developer, Advocate!

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

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

Встретил отличный пример такой ссылки в доке Google Search Console:
«This report is much easier to understand if you have read how Google Search works first.»

Это так душевно звучит, с заботой о читателе.
источник
2020 July 20
DocOps
Ищу рассказчиков о провалах в IT.

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

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

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

Если вам есть, что рассказать, пишите мне, @nick_volynkin. Если сомневаетесь, тем более пишите, обсудим. :) Можно и сразу подать заявку, выбирайте там секцию FailPy, тогда заявка будет видна только программному комитету.
источник
2020 July 21
DocOps
​​Вебинар про документацию, 22 июля (среда), 12:00 Мск.

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

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

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

Регистрация: http://amp.gs/wkym
источник
DocOps
Быстрые результаты в управлении знаниями, 22 июля (среда), 14:30–16:00 Мск.

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

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

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

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

Регистрация: tsupko-tech.timepad.ru/event/1357069
источник
2020 July 24
DocOps
Дайджест чата и результаты исследования.

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

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

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

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

(Если вы не узнали, Xsolla — это те самые ребята в авангарде непрерывной локализации, которые внедрили Serge, когда это ещё не было мейнстримом.)
источник
2020 July 29
DocOps
Архитекторы говорят про документацию сегодня в 20:00 Мск.

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

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

Ссылка и все подробности в канале: https://t.me/it_arch/871
источник
2020 August 07
DocOps
​​Только мне кажется, что тут всё перепутано? Метод open же должен открывать существующий файл, а new — делать новый.
Или всё правильно?

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

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

Спасибо @dside_ru, что объяснил про конструктор.
источник
2020 August 13
DocOps
Тоня шарит! Мне тоже помогает такое.
https://t.me/Editors_cave/158
источник
2020 August 14
DocOps
Перекличка :)
1. Откройте https://developers.google.com/speed/pagespeed/insights/
2. Проверьте там стартовую страницу своей документации (или просто сайта).  3. Какой результат на мобилке? 4. Ссылку на проверку можно запостить в @docsascode
Анонимный опрос
17%
0–24
15%
25–49
13%
50–74
20%
75-89
35%
90–100
Проголосовало: 60
источник
DocOps
Следующая задача — вытащить документацию из кода.
https://twitter.com/sigsergv/status/1293738764658003970
источник
2020 August 29
DocOps
📈 Высокой культуры пост

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