FAQ по архитектуре и работе ВКонтакте.
Алексей Акулович, ВКонтакте

Доклад-экскурсия по архитектуре VK. В конце конспекта — ссылки на другие доклады по конкретным аспектам архитектуры. https://github.com/NickVolynkin/highload-2018/blob/master/2.1-vk-architecture.md

Тем временем, Лана Новикова на Highload провела и законспектировала митап про управление знаниями.

А ещё она уже некоторое время в тайне от всех ведёт канал про управление знаниями. Давайте сделаем тайное явным и вместе подпишемся на @the_know_all.

Делюсь конспектом и слайдами с митапа Управление знаниями по принципам DevOps, очень продуктивная дискуссия получилась

https://gist.github.com/lananovikova10/1e19e169d7365b958b7a4d15491a6b00

Монолит для сотен версий клиентов: как мы пишем и поддерживаем тесты.
Владимир Янц, Badoo

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

В конце слайдов были полезные ссылки от докладчика, я их скопировал в конспект.

https://github.com/NickVolynkin/highload-2018/blob/master/2.2-testing-badoo.md

Как устроить хайлоад на ровном месте.
Олег Бартунов, Федор Сигаев, Postgres Professional

Олег и Фёдор подробно рассказывают, какие ошибки приведут вас к хайлоаду, деградации сервисов и тотальному аду. Часть ошибок — общие, часть специфичны для PostgreSQL.

Вот это для меня стало прямо-таки откровением: «Поисковые системы лучше всего ищут в ночь с субботы на воскресенье. Когда нагрузки больше, они ограничивают задачу, чуть ухудшают качество, но зато не деградируют.»

А ещё Олегу дважды звонили по телефону, он поднимал трубку и говорил «я занят!». Я уже надеялся, что это постановка и в конце ему выкатят тележку как из супермаркета, полную звонящих телефонов — будет хайлоад. Но так не случилось.

Конспект на GitHub.

Как стать классным спецом по базам данных
Илья Космодемьянский, Data Egret

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

А ещё Илья рекомендует будущим DBA общаться с разработчиками и нести им знания о БД, чтобы они лучше понимали и делали меньше ошибок. Вот буквально так:
— учиться говорить, писать и читать по-русски и по-английски;
— делать доклады, выступать на митапах и подаваться на Highload.

Конспект: https://github.com/NickVolynkin/highload-2018/blob/master/2.4-dababase-pro.md

#highload2018 #highload

Документация для SRE
#seeking_sre #sre

В сентябре 2018 года вышла книга Seeking SRE от издательства O'Reily. В ней есть целая глава про документацию команды SRE.
Буду понемногу конспектировать-переводить эту главу. Вот первая часть.

Часть 1/21. Качество документации
Как определить качество командной документации? Есть два аспекта качества:

1. Структурное качество. Документация выглядит так, как должна:
   — Текст без орфографических ошибок.
   — Сответствует гайдлайнам по стилю.
   — Использует правильный тон.
   — Хорошо организована, в ней легко ориентироваться.

2. Функциональное качество. Хорошая документация решает задачу, для которой написана.
Например, для оценки качества плейбука (playbook, runbook) стоит задать такие вопросы:
   — Покрывает ли 100% возможных алертов (alerts, чрезвычайных ситуаций)?
   — Может ли команда полагаться на этот плейбук для решения своих задач?
   — Насколько плейбук «highly available».
     Если дока по починке k8s лежит в wiki, которая хостится в этом же k8s, то когда тот упадёт, дока будет недоступна.
   — Насколько легко добавлять и обновлять документы?
   — Насколько описание каждого алерта точное и полное?
   — Даёт ли каждый документ достаточно информации, чтобы понять и разрешить алерт?
   — Есть ли в документе инструкции по эскалации?

Функциональное качество важнее структурного:

Хорошая структура + плохое содержание = плохая документация.
Так себе структура + хорошее содержание = хорошая документация.
Отличная структура + отличное содержание = идеальная документация. Но она бесконечно дорогая и недостижима на практике, как 100% доступность/аптайм.

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

Спасибо Игорю Курочкину из Express42 за то, что порекомендовал мне эту книгу. Кстати, в ближайшую неделю её можно будет купить в составе Humble Bundle: DevOps by O'Reilly.

Приходите обсуждать SRE-доки в чат @docsascode.

​​Documentation Doctors на DevFest Siberia.

В этом году мы с коллегами из сообщества техписателей уже дважды приходили на конференции со стендом Documentation Doctors. К нам приходят с вопросами о том, почему никто не пишет документацию, почему никто её не читает, как задокументировать легаси без исходного кода и как писать case-study, чтобы было понятно инвесторам из долины.

23-25 ноября мы отправляемся на ещё одну конференцию — DevFest Siberia 2018. Все три дня будем общаться с вами на стенде, наверняка ещё устроим митап. Приходите просто поговорить или порешать конкретные проблемы с вашими доками.

Вот фото, чтобы вы нас узнали на DevFest'е. Мы будем точно такие — в белых халатах, с табличками и с умным выражением лица.

Ещё 4 конспекта Highoad++.
Эксперимент с конспектированием Highload++ в целом прошёл удачно. На выходных законспектирую ещё 3-4 доклада, а потом напишу краткий отчёт по эксперименту.

Порекомендуйте, что стоит посмотреть? Какие доклады были самые огненные, самые полезные? Пишите мне личным сообщением (@nick_volynkin) или в @docsascode.

​​Зачем выделять внутристрочный код.
Это спонсорский пост. Боль и гнев для его написания предоставлены документацией OASIS.

Если документация рассказывает о программном коде, то все фрагменты кода должны быть отличимы от обычного текста. Для этого код внутри абзацев форматируют стилем «внутристрочный код» (inline code, вот так). Это очень помогает читать и понимать текст.

А если так не делать, то читатель будет думать, что же такое «именейшие и именоватые атрибуты»:

​​Вот так гораздо лучше. Ещё термин выделим, это тоже не просто текст.

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

Собрал вместе свои посты с #Highload2018 http://mtsepkov.org/Highload-2018. Мне конференция дала рад выпуклых картин устройства цифрового мира, которые интересны не только IT-шникам - они показывают способы организации деятельности, а не только технологии. О технологиях тоже было много докладов, но нельзя объять необъятное в количестве 19 треков, так что в этой части отчет не репрезентативен.

Дата-инженеры и кому они нужны.
Валентин Гогичашвили, Zalando SE

Доклад отвечает на вопросы:
— Что нужно дата-саентистам, чтобы не терять 80% времени на борьбу с инструментами? Нужна платформа для работы с данными.
— Кто будет её делать? Специальные инженеры, но ни в коем случае не сами саентисты.
— Как её делать? Как обычный продукт: изучать потребителей, проверять гипотезы, доставлять небольшими итерациями. И как обычную платформу как сервис: использовать готовые инструменты, обмазать автоматизацией и метриками, обучать пользователей.

Беру пример с Максима Цепкова: постарался написать более связный текст, нашёл переводы почти всех терминов. https://github.com/NickVolynkin/highload-2018/blob/master/1.9-data-engineers.md.

#highload2018

Uptime day, прямую текстовую трансляцию ведёт Игорь Курочкин:
https://github.com/ikurochkin/uptimeday-3-2018/blob/master/README.md

Там ещё есть «Цель 2», «Критическая цепь» и, в переложении на IT, «Проект Феникс». Все читал, и все очень рекомендую.

Столкновения с реальностью пост
Подсунули мне тут книгу Голдратта "Цель". И вот там прямо написаны те вещи, которые на айтишных конференциях начали озвучивать года два как. По сути - про этот самый devops, разрушение оков и ускорение процессов во имя получения результатов asap.
Ключевое отличие книги от обсуждений в народе: в книге есть фундаментальное обоснование, из которого можно вывести все остальные принципы. Народ же в основном размахивает трусами и дерётся за терминологию, вместо сути.

Читаю, значит, и думаю попутно: "Интересно, книга написана по мотивам движухи за devops и agile, или наоборот, движуха поднялась по мотивам книги?". А потом вижу прекрасное: книга написана в 1984 году.

Марк Бейкер

Марк Бейкер — известный технический писатель. Сегодня он написал в своём блоге примерно следующее: «Я вырастил детей, заплатил ипотеку, написал две книги о технической документации и накопил достаточно денег. Хватит технического писательства, буду писать художку.»

Успехов на новом пути, Марк!

https://everypageispageone.com/2018/11/26/turning-a-page/

Митап WTD Moscow#2: видео и конспекты.

В октябре прошёл второй митап Write the Docs Moscow. Недавно мы опубликовали видео, а ещё Лана Новикова сделала конспекты докладов и опубликовала их на Хабре.

Читайте статью, ставьте Лане плюсы, смотрите видео — ссылки в статье.

Доклады были вот такие:

— Антон Телин, «Зачем и как мы делаем видеоинструкции».
— Николай Волынкин, «Технический писатель 2.0.1»
— Константин Валеев, «Foliant»
— Никита Самохвалов, «Исчерпывающая документация на RESTful API»
— Светлана Новикова, «Управление знаниями с помощью матрицы компетенций»
— Данила Медведев, «НейроКод».

#writethedocs #writethedocs_moscow

​​Иногда документация бывает слишком минималистична: