Заметки VP по разработке

Сергей Лысцев, вице-президент по разработке в Plesk пишет дельные заметки об управлении разработчиками, метриках, планах, бюджетах и в целом об индустрии: @program_man.

Вообще в Plesk хорошая культура управления, субъективно лучшая из всех мест, где я работал. Заметки Сергея помогают мне немного заглянуть в головы наших менеджеров и понять, как всё устроено.

Вот заметки, которые мне больше всего зашли:

— Почему перерабатывать вредно, с доказательствами.

— Баланс в планировании и оценке сроков.

— Метрики эффективности инженеров.

— Полезный и бесполезный сторителлинг.

— Как мы чуть не потеряли всю внутреннюю документацию.

Диплом как код

На Хабре вышла статья «Как я диплом в LaTeX писал с GitHub, Docker и TravisCI»

https://habr.com/post/424805/

Вот она, документация будущего.

Детали тут: https://beakerbrowser.com/docs/

Митап 14 октября в Москве: техническая коммуникация / управление знаниями

По традиции, еду из Новосибирска, чтобы организовать митап Write the Docs Moscow.
В программе три-четыре коротких доклада, форсайт-сессия и афтепати. Темы докладов скоро будут в @docops.

Что делать участникам:

0. Если хотите выступить, подайте заявку на доклад. За две недели можно подготовить отличный доклад, организаторы вам помогут.
1. Зарегистрируйтесь на митап. Вход свободный, но места ограничены.
2. Позовите на митап коллег!
3. Готовьтесь к афтепати. После митапа отправимся в Гастропаб 31 на Шаболовке, это в том же здании.

Ссылка на трансляцию будет в @docops перед началом митапа. Записи докладов будут позже на YouTube.

Обсуждение — в чате @docsascode.

#writethedocs #writethedocs_moscow

​​Кружка «Яндекс»

Посмотрите, какая классная инструкция на коробке у фирменной кружки Яндекса! Человеческий текст, понятные заголовки, список с тире, вёрстка хорошая.

Сама кружка тоже хороша, рекомендую.

​​Как фичи текстового редактора вредят автору.

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

Обычно абзацы в тексте и так разделяются: увеличенным расстоянием между строками, реже красной строкой или как-то ещё. Стиль абзаца задаётся один раз на весь документ: в CSS для веба или в настройках визуального (WYSIWYG) редактора. Авторы не должны вручную менять стиль конкретных элементов текста. Зачем же они это делают? А потому что могут.

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

Легковесные языки разметки, напротив, дают автору очень мало свободы, зато исправляют ошибки за автора. Так, в Markdown, rST и AsciiDoc любое количество пустых строк — это просто начало нового абзаца, а все абзацы имеют один стиль. Фичи «испортить дизайн» просто нет.

Языки разметки — как кубики Лего. Они жесткие, соединяются только как задумано, зато из них можно город построить. А визуальные редакторы — как песок. Как будто бы у вас полная свобода, но на деле вы будете бегать и исправлять осыпающиеся стенки.

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

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

#docops_markups #docops_bestpractice

Как продать начальнику новую структуру документации?

Вопрос от читательницы канала:

У нас вики в очень плохом состоянии. Хочу предложить начальнику свой вариант, как организовать документацию.

Общая ситуация такая: вся документация перепутана. Она сложная, потому что система непростая. Новая структура документации должна помочь в работе сотрудникам. Они будут точно знать, где и какой документ искать, где и по каким шаблонам содавать документы. Начальство предлагает упростить документацию, но общего видения нет. И я понимаю, что предложения начальства тоже не принесут желаемого результата.

Как „продать” начальнику свой вариант, какие аргументы привести? Как себя вести в таких случаях?

Приходите обсудить этот вопрос в www.tg-me.com/docsascode. Свой ответ я туда же напишу.

​​Шрифт Sans Forgetica

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

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

Сайт шрифта: http://www.sansforgetica.rmit/

Статья на сайте RMIT University: https://www.rmit.edu.au/news/all-news/2018/oct/sans-forgetica-news-story

Статья на Хабре про шрифт: https://habr.com/post/425529/

Для примера — Agile Manifesto (http://agilemanifesto.org/) шрифтом Sans Forgetica:

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

Как «продать» начальнику новую структуру документации, ответ Андрея Гаврилова, системного аналитика в СМСФинанс:

Начальство всегда покупает варианты, в которых есть деньги. В идеале — посчитанные, но и простого понимания, что там есть деньги — может быть достаточно.

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

Аналогично можно собрать статистику по тому, как часто сотрудникам не удаётся найти информацию, которая реально в документации есть, и, опять же, прикинуть, насколько новая структура улучшит ситуацию.

Как «продать» начальнику новую структуру документации, ответ Максима Лапшина (CTO в Flussonic):

Я думаю, что лучше всего, когда есть какие-то метрики. Например, среднее время пребывания клиента в разделе документации или метрики удовлетворенности клиентов, когда поддержка кидает им ссылку на документацию. Или поиск суппортерами документации и т.п.

Bот если есть метрики, дальше гораздо проще говорить об измеряемых изменениях.

Как «продать» начальнику новую структуру документации, ответ Сергея Лысцева (VP Development в Plesk):

«Продать» это всегда про объяснить выгоду клиенту на его собственном языке. Иногда это деньги, иногда это метрики, но совсем не обязательно ими ограничиваться.

Из текста мы видим, что решение уже ищется, причем ищется самим начальством, то есть продавать саму необходимость решения уже не надо. Надо продать только именно свое решение (против всех остальных). Это скорее всего отсекает деньги и метрики как аргументы — ни то, ни другое не получится уверенно сравнить между разными вариантами решений.

Что остается? Для начальника всегда работает аргумент избавиться от проблемы для него самого — то есть предложить самой заняться вопросом и решить его своим способом. Изложить предлагаемый способ понадобится только для того, чтобы продемонстрировать cdj. компетентность и внушить начальнику уверенность, что у тебя получится. Хотя самого решения будет мало — будет влиять как тебя сейчас видят в организации, доверяют ли и т.п. Никогда не будет лишним заручиться поддержкой коллег. Если кто-то еще считает ваш план хорошим, весы будут легче склоняться в вашу сторону.

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

Есть тонкий момент с эго начальника. Если оно великовато, то начальник может возбудиться, что делаться будут не его идеи, а какие-то другие. И тогда найдутся причины почему нет. Тогда надо аккуратно продать начальнику, что это все его собственные идеи. Или подписаться внедрить его идеи, протащить за ними следом свои собственные и затем всем (и самому начальнику) рассказать, что это были идеи начальника. 🙂

WTD Moscow #2: Антон Телин, видеоинструкции.

Наконец-то анонсируем доклады на предстоящем митапе Write the Docs в Москве 14 октября.
Лучше поздно, чем никогда.

Начнём с доклада Антона Телина про документацию в формате видеоинструкций.

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

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

Приходите послушать Антона уже в это воскресенье. Зарегистрируйтесь здесь: митап Write the Docs #2.

#writethedocs #writethedocs_moscow

WTD Moscow #2: Константин Валеев, Foliant.

Продолжаем анонсировать доклады на митапе Write the Docs в Москве 14 октября.

Константин Валеев из компании Рестрим расскажет о Foliant — их собственной реализации docops workflow на основе языка Markdown. Год назад Константин уже рассказывал про Foliant, и с тех пор поменялось очень многое.

Расскажу про Foliant — наш Markdown-based инструмент для ведения документации, который мы написали (и выложили на гитхаб) потому что нам не подошёл ни один готовый. Расскажу почему и как мы стали собирать своё решение, а не взяли Sphinx или AsciiDoctor (скорее всего вам так делать не нужно); как мы его развивали и чему научили; как мы им пользуемся и как планируем развивать дальше.

Foliant на гитхабе: https://github.com/foliant-docs/foliant.

Митап будет в Москве, 14 октября, с 13:00. Зарегистрируйтесь здесь: митап Write the Docs #2.

#writethedocs #writethedocs_moscow

WTD Moscow #2: Никита Самохвалов, «Исчерпывающая документация на RESTful API».

Ещё один доклад на митапе Write the Docs в Москве 14 октября.

Никита Самохвалов из компании Нотамедиа расскажет о том, как документировать RESTful API с помощью Open API Specification.

Когда огрызки недодокументации на API вызывают негодование, а процесс написания оной доставляет немало хлопот, самое время подумать об автоматизации. В каком формате писать? Что писать? Как проверять? Приходите на митап, чтобы узнать, как изо дня в день инженеры «Нотамедии» решают подобные задачи.

Москва, 14 октября, начало в 13:00. Вы знаете, что делать.

#writethedocs #writethedocs_moscow

WTD Moscow #2: Данила Медведев, НейроКод.

Ещё один доклад на митапе Write the Docs в Москве 14 октября. Наконец мы добрались до управления знаниями.

Данила Медведев расскажет про инструмент для моделирования и хранения знаний под названием «НейроКод». Я видел этот инструмент и немного пользовался — очень крутая штука, принципиально отличается от всех баз знаний, вики и заметок, которые я когда-либо видел. Деталей не расскажу, потому что NDA. Зато их расскажет Данила.

Вот небольшое введение в тему от автора:

Новое комплексное архитектурное решение для решения основной задачи ИТ. DKR, OHS, усиление интеллекта, фрактальность, spatial hypertext, ZUI, моделирование, бизнес- и ИТ-архитектура, управление знаниями, PIM/GIM.

Концепция документации была сформулирована в книге "Traité de documentation: le livre sur le livre, théorie et pratique" Пола Отлета, создателя прото-Интернета и сооснователя Лиги Наций. Затем область документации разошлась на два направления — электронного документооборота ("Toward Paperless Information Systems" Фредерика Ланкастера) и человеко-машинного симбиоза ("Man-Computer Symbiosis" Джозефа Ликлайдера и "Augmenting Human Intellect: A Conceptual Framework" Дугласа Энгельбарта).

Я расскажу про второе направление. Для организации информации Энгельбарт предложил архитектуру Open Hyperdocument System/Dynamic Knowledge Repository. Из существующих концепций именно она лучше всего описывает, что мы делаем, разрабатывая технологию НейроКод. Эта технология также базируется на принципе фрактальной организации сетей информации и концепции масштабируемого интерфейса.

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

Если вы мало что поняли и не знаете все эти аббревиатуры — дайте я вас обниму, я тоже не знаю. Приходите на митап, поймём и узнаем вместе.

Зарегистрируйтесь и напишите своё настоящее имя и фамилию — вход строго по записи, охрана строгая.

#writethedocs #writethedocs_moscow

Пирамида рецензирования

В разработке документации есть этапы (слои) рецензирования. Это порядок проверки документа, он примерно такой:

— сам перечитал и проверил на грубые ошибки;
— отдал коллеге на проверку грамотности, структуры и стиля;
— отдал эксперту на проверку смысла и содержания.

Если на конкретном этапе есть замечания, документ возвращают доработку, а не передают дальше.

А в тестировании есть понятие «пирамида тестирования». Тесты выполняются в таком порядке:

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

Если на конкретном уровне продукт не проходит тесты, то тесты на более высоком уровне не имеют смысла; продукт возвращают на доработку.

Кажется, между рецензированием документа и тестированием продукта есть что-то общее.

Нашёл хороший канал про UX, а в нём рекомендации, как писать тексты в интерфейсе:

https://www.tg-me.com/uxnotes/186