Всем доброе утро,
Уже через час откроется регистрация на Гипербатон.
Для тех,  кто не сможет присутствовать лично,  трансляция будет доступна на странице мероприятия: https://events.yandex.ru/events/hyperbaton/22-sep-2018/
Вопросы к докладчикам можно оставлять под трансляцией или отправлять в это чат

Трансляция началась, подключайтесь!
https://events.yandex.ru/events/hyperbaton/22-sep-2018/

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

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

СОЛДАТЫ И НАЁМНИКИ

Бизнес — это война, а все работники условно делятся на солдат и наёмников.

Эти два типа людей различаются примерно всем. Если вы с солдатами попробуете обращаться как с наёмниками, то быстро останетесь без бойцов. Если вы наёмник в роте солдат, то уютненько вам не будет.

Вот некоторые мои соображения по этому поводу:

Функционал
Солдат — узкий специалист. Никому не придёт в голову отправлять лучников таранить ворота замка. Солдат растёт и развивается в рамках своей специализации. Если он чего-то не умеет, его обучают организованно, вместе с другими. Из-за того, что в традиционных армиях для каждой задачи создают своё подразделение, они как правило крупные.

Наёмник чаще универсал или по крайней мере имеет какие-то дополнительные навыки. Если в бою понадобится бросить лук и рубиться мечом, он так и сделает. Своим обучением наёмник занимается сам, потому что от этого зависит его заработок и жизнь. Отряды наёмников обычно меньше и задачи получают разные, часто комплексные и без подробного плана.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например, один из вариантов будущего интернета. Обратите внимание на url

Митап 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

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

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

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

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

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

Приходите обсудить этот вопрос в t.me/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