​​Подкаст Art of Programming про документацию

Выпуск подкаста «Art of Programming» про техническую документацию в Plesk и вообще. Ведущий — Антон «Голодный» Черноусов, в гостях я и мой коллега из Plesk, Java-разработчик Денис Горбатых.

http://blog.golodnyj.ru/2018/09/171-art-of-programming-highload.html?m=1

На фото мы заняли переговорку наших HR'ов и готовимся к записи.

Смотрите, какие классные обложки у выпусков подкаста:
https://twitter.com/golodnyj/status/1037889400590540800

Новости с Write The Docs Prague 2018

Сегодня проходит Writing Day.

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

Обсуждаются такие темы:

1. Migrating docs to another tool
2. Blogs
3. Generatin Flare Snypets with Python
4. Extracting labels from source code to use as variables in Flare
5. MDN web DOCS
6. How to incentivise devs to write the docs?
7. Documenting CI/CD Cloud-based software
8. API Docs (Slate & other SSGs)
9. Write your own docs/Docs strategy
10. Guidelines for writing the Best online Documentation and building website for it
11. Rewrite the content (JetBrains)

​​Don't say “simply”, Jim Fisher

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

Пример: чтобы установить приложение в macOS, нужно «просто перетащить» иконку приложения на ярлык «Applications». Но Джим понял это далеко не сразу. Как он говорит, — «действительно, это настолько „просто“, что разработчик специально написал, что это просто».

Идея: мы путаем «ease», лёгкость, и «simplicity», простоту. Пользователю становится просто, когда он уже освоил кучу требуемых концептов. Слово «simply» описывает действия, но не концепты.

Полный конспект доклада: https://github.com/NickVolynkin/wtd-prague-2018/blob/master/dont-say-simply.md

Программа Гипербатона.

Организаторы опубликовали программу Шестого Гипéрбатона.

Участие бесплатное, но по приглашениям. Чтобы получить приглашение, зарегистрируйтесь на сайте.

Темы:

— Текст как данные: автоматизируем формирование контента.
— Контент-стратегия: новый уровень экспертизы.
— Новый взгляд на документирование API и SDK в Яндексе.
— Машинный перевод: опыт Яндекса.
— Ландшафт сервисов облачного машинного перевода.
— Как работают разные инструменты автоматизации перевода и как их выбирать.

Доклад бывшего коллеги на DevOpsDays Moscow про то, как эксплуатации жить с сервисами - https://www.youtube.com/watch?v=j9I4oeEXBO8

Все боли очень знакомые:

- нет документации ("Если документации нет - значит никто не скажет, что она плохая!"),

- сервис передали другой команде и теперь там никто не знает, что с ним делать,

- уволился менеджер, который знал как там все должно было работать,

- партизанская разработка ("мы тут быстренько что-то сделали и оно уже приносит деньги!")

-сервис написали аутсорсеры, его приняли и теперь надо как-то с ним жить дальше.

И решения тоже понятные, знакомые и очевидные. Документация, регламенты, передача знаний внутри компании.

Но вот в реальной жизни это все раз от раза не работает(

Всем доброе утро,
Уже через час откроется регистрация на Гипербатон.
Для тех, кто не сможет присутствовать лично, трансляция будет доступна на странице мероприятия: 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/

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