Привет, давайте знакомиться!
Я работаю техническим писателем в Plesk, внедряю практику «документация как код», пишу в этом канале про документацию и управление знаниями, организую митапы на те же темы. Посты в канале обсуждают в чате @docsascode.
Сегодня я смотрю Highload++, на ходу пишу и оформляю конспекты, и сразу их публикую на GitHub. Это эксперимент, он уже точно удачный, так что я и дальше буду так делать.
Если ваша документация болит и требует улучшения — давайте обсудим, пишите @nick_volynkin. Я сейчас не беру заказы на разработку документации, но посоветую вам хорошего аутсорсера.
Если вы хотите рассказать о том, как вы пишете и автоматизируете доки, внедряете управление знаниями, решаете другие задачи бизнеса с помощью технического текста — это очень круто, жду вас на митапе в Москве, Питере, Новосибирске или других городах. Пожалуйста, заполните форму заявки, я вам отвечу.
До связи,
Николай Волынкин.
Я работаю техническим писателем в Plesk, внедряю практику «документация как код», пишу в этом канале про документацию и управление знаниями, организую митапы на те же темы. Посты в канале обсуждают в чате @docsascode.
Сегодня я смотрю Highload++, на ходу пишу и оформляю конспекты, и сразу их публикую на GitHub. Это эксперимент, он уже точно удачный, так что я и дальше буду так делать.
Если ваша документация болит и требует улучшения — давайте обсудим, пишите @nick_volynkin. Я сейчас не беру заказы на разработку документации, но посоветую вам хорошего аутсорсера.
Если вы хотите рассказать о том, как вы пишете и автоматизируете доки, внедряете управление знаниями, решаете другие задачи бизнеса с помощью технического текста — это очень круто, жду вас на митапе в Москве, Питере, Новосибирске или других городах. Пожалуйста, заполните форму заявки, я вам отвечу.
До связи,
Николай Волынкин.
Вадим Мадисон из Авито, «Что мы знаем о микросервисах».
Вадим рассказывает в том числе про требования к документации для микросервиса. Они прям всерьёз требуют документацию и без неё не принимают микросервис от разработчиков. Вот что в неё входит:
— Описание сервиса. В двух предложениях, что сервис делает.
— Диаграмма архитектуры.
— Runbook. (Про них я скоро опубликую конспект из книги Seeking SRE)
— FAQ
— Описание API endpoints
— Labels — к какому продукту, функциональности и структурному подразделению относится сервис.
— Владельцы кода.
Конспект здесь: https://github.com/NickVolynkin/highload-2018/blob/master/1.1-microservices.md
Вадим рассказывает в том числе про требования к документации для микросервиса. Они прям всерьёз требуют документацию и без неё не принимают микросервис от разработчиков. Вот что в неё входит:
— Описание сервиса. В двух предложениях, что сервис делает.
— Диаграмма архитектуры.
— Runbook. (Про них я скоро опубликую конспект из книги Seeking SRE)
— FAQ
— Описание API endpoints
— Labels — к какому продукту, функциональности и структурному подразделению относится сервис.
— Владельцы кода.
Конспект здесь: https://github.com/NickVolynkin/highload-2018/blob/master/1.1-microservices.md
Тернии контейнеризированных приложений и микросервисов
Иван Круглов, Booking.com
Очень толковый доклад о проблеме, двух неудачных и одной удачной попытке решения. Полный конспект: https://github.com/NickVolynkin/highload-2018/blob/master/1.2-per-aspera-ad-paas.md
Ключевые мысли:
Мысль 1: не стоит недооценивать способность кода выживать. Если вы что-то написали, этим внезапно будут пользоваться. Если там баги, люди с ними столкнутся и будут требовать исправлений.
Мысль 2: лучше скучный инструмент, который вы можете освоить, чем крутецкий, но слишком сложный.
Мысль 3: стоит заранее сформулировать ожидания пользователей от системы и системы от пользователей.
Мысль 4 (продолжение второй): kubernetes хорош, но важнее подумать о том, как вы будете его интегрировать в сществующую экосистему. Только если вы не стартап, все такие cloud-native.
Иван Круглов, Booking.com
Очень толковый доклад о проблеме, двух неудачных и одной удачной попытке решения. Полный конспект: https://github.com/NickVolynkin/highload-2018/blob/master/1.2-per-aspera-ad-paas.md
Ключевые мысли:
Мысль 1: не стоит недооценивать способность кода выживать. Если вы что-то написали, этим внезапно будут пользоваться. Если там баги, люди с ними столкнутся и будут требовать исправлений.
Мысль 2: лучше скучный инструмент, который вы можете освоить, чем крутецкий, но слишком сложный.
Мысль 3: стоит заранее сформулировать ожидания пользователей от системы и системы от пользователей.
Мысль 4 (продолжение второй): kubernetes хорош, но важнее подумать о том, как вы будете его интегрировать в сществующую экосистему. Только если вы не стартап, все такие cloud-native.
Data Discovery в микросервисной архитектуре
Николай Голов, Avito
Доклад о том, как создать и поддерживать цифровой двойник всей инфраструктуры данных в большой компании — Persistent Fabric, «помнящая ткань».
Из ответов на вопросы после доклада: Fabric — это ткань, а ни в коем случае не фабрика. Не стройте фабрику данных (джависты, вам!), это тупиковый путь. ))
https://github.com/NickVolynkin/highload-2018/blob/master/1.3-data-discovery.md
Николай Голов, Avito
Доклад о том, как создать и поддерживать цифровой двойник всей инфраструктуры данных в большой компании — Persistent Fabric, «помнящая ткань».
Из ответов на вопросы после доклада: Fabric — это ткань, а ни в коем случае не фабрика. Не стройте фабрику данных (джависты, вам!), это тупиковый путь. ))
https://github.com/NickVolynkin/highload-2018/blob/master/1.3-data-discovery.md
Базы данных и Kubernetes
Дмитрий Столяров, Флант
Если вы настолько любите kubernetes, что хотите положить в него вообще всё, в том числе базы данных и другой stateful — вот вам подробная инструкция от Дмитрия Столярова из Фланта.
Если вы сомневаетесь, вот что об этом думает докладчик. Технологии развиваются волнами. Сначала технология появляется, потом она становится простой. Пока что стейтфул в k8s — уже можно, но ещё сложно, но со временем станет проще и лучше.
А ещё компания Флант делает инструмент https://github.com/flant/dapp.
Конспект: https://github.com/NickVolynkin/highload-2018/blob/master/1.4-bd-k8s.md
Дмитрий Столяров, Флант
Если вы настолько любите kubernetes, что хотите положить в него вообще всё, в том числе базы данных и другой stateful — вот вам подробная инструкция от Дмитрия Столярова из Фланта.
Если вы сомневаетесь, вот что об этом думает докладчик. Технологии развиваются волнами. Сначала технология появляется, потом она становится простой. Пока что стейтфул в k8s — уже можно, но ещё сложно, но со временем станет проще и лучше.
А ещё компания Флант делает инструмент https://github.com/flant/dapp.
Конспект: https://github.com/NickVolynkin/highload-2018/blob/master/1.4-bd-k8s.md
Apache Kafka как основа для велосипедостроения
Николай Сивко, okmeter.io
Очередной доклад с Highload 2018. Николай рассказывает о том, как сделать свою time-series database, используя Apache Kafka в качестве WAL (write ahead log).
Краткие выводы. Если вы хотите написать свою специализированную БД:
— Подумайте 100 раз
— разберитесь, как работают взрослые БД
— используйте kafka в качестве wal
— напишите остаток кода
Конспект: https://github.com/NickVolynkin/highload-2018/blob/master/1.5-kafka-bicycle.md
Николай Сивко, okmeter.io
Очередной доклад с Highload 2018. Николай рассказывает о том, как сделать свою time-series database, используя Apache Kafka в качестве WAL (write ahead log).
Краткие выводы. Если вы хотите написать свою специализированную БД:
— Подумайте 100 раз
— разберитесь, как работают взрослые БД
— используйте kafka в качестве wal
— напишите остаток кода
Конспект: https://github.com/NickVolynkin/highload-2018/blob/master/1.5-kafka-bicycle.md
Разгоняем обработку событий до 1.6М/сек. Опыт Badoo
Александр Крашенинников, Badoo
Хороший ликбез про построение системы сбора статистики. А ещё Александр хвалит ClickHouse: «Инструмент классный, документация ваще огонь, я сам туда писал».
Конспект тут: https://github.com/NickVolynkin/highload-2018/blob/master/1.6-accelerate-events.md
Немного о том, как я пишу эти конспкты:
1. Смотрю, вроде бы всё понятно.
2. Моргнул.
3. Что это вообще на слайде? О чём докладчик говорит? Ничего не понятно!
Александр Крашенинников, Badoo
Хороший ликбез про построение системы сбора статистики. А ещё Александр хвалит ClickHouse: «Инструмент классный, документация ваще огонь, я сам туда писал».
Конспект тут: https://github.com/NickVolynkin/highload-2018/blob/master/1.6-accelerate-events.md
Немного о том, как я пишу эти конспкты:
1. Смотрю, вроде бы всё понятно.
2. Моргнул.
3. Что это вообще на слайде? О чём докладчик говорит? Ничего не понятно!
Топ ошибок со стороны разработки при работе с PostgreSQL.
Алексей Лесовский, Data Egret
Отличный доклад. Алексей раскладывает все проблемы с PostgreSQL по категориям, перечисляет основные ошибки внутри категорий, предлагает решения.
А ещё как техписателю и иногда докладчику мне нравится вот что:
— Сразу объявил структуру доклада, очень чётко по ней шёл и в конце повторил тезисно. Так слушателям гораздо понятнее, где они находятся. А ещё так запоминается лучше. Будете о чём-то рассказывать — пожалуйста, делайте так.
— Термины вводил сразу на русском и английском. Это помогает сопоставить оригинальный термин с переводом и не плодить зоопарк терминов. Например: «Внешние таблицы (foreigh tables), декларативное партиционирование (declarative partitioning)». Так я тоже рекомендую делать в докладах и документации, особенно в переводах статей.
Ещё у Алексея есть документ с подборкой хороших практик: https://github.com/lesovsky/postgres-commandments/blob/master/README.md.
Конспект доклада: https://github.com/NickVolynkin/highload-2018/blob/master/1.7-postgresql-errors.md.
Алексей Лесовский, Data Egret
Отличный доклад. Алексей раскладывает все проблемы с PostgreSQL по категориям, перечисляет основные ошибки внутри категорий, предлагает решения.
А ещё как техписателю и иногда докладчику мне нравится вот что:
— Сразу объявил структуру доклада, очень чётко по ней шёл и в конце повторил тезисно. Так слушателям гораздо понятнее, где они находятся. А ещё так запоминается лучше. Будете о чём-то рассказывать — пожалуйста, делайте так.
— Термины вводил сразу на русском и английском. Это помогает сопоставить оригинальный термин с переводом и не плодить зоопарк терминов. Например: «Внешние таблицы (foreigh tables), декларативное партиционирование (declarative partitioning)». Так я тоже рекомендую делать в докладах и документации, особенно в переводах статей.
Ещё у Алексея есть документ с подборкой хороших практик: https://github.com/lesovsky/postgres-commandments/blob/master/README.md.
Конспект доклада: https://github.com/NickVolynkin/highload-2018/blob/master/1.7-postgresql-errors.md.
«Платформа» в Badoo: как мы построили инфраструктурную разработку.
Антон Поваров, Badoo
Доклад про становление инфраструктурной команды, её роль в компании, задачи и взаимодействие с разработчиками и бизнесом.
Конспект: https://github.com/NickVolynkin/highload-2018/blob/master/1.8-badoo-infradev.md
Это последний доклад на сегодня. Хорошего вам отдыха, встретимся завтра.
Антон Поваров, Badoo
Доклад про становление инфраструктурной команды, её роль в компании, задачи и взаимодействие с разработчиками и бизнесом.
Конспект: https://github.com/NickVolynkin/highload-2018/blob/master/1.8-badoo-infradev.md
Это последний доклад на сегодня. Хорошего вам отдыха, встретимся завтра.
FAQ по архитектуре и работе ВКонтакте.
Алексей Акулович, ВКонтакте
Доклад-экскурсия по архитектуре VK. В конце конспекта — ссылки на другие доклады по конкретным аспектам архитектуры. https://github.com/NickVolynkin/highload-2018/blob/master/2.1-vk-architecture.md
Алексей Акулович, ВКонтакте
Доклад-экскурсия по архитектуре VK. В конце конспекта — ссылки на другие доклады по конкретным аспектам архитектуры. https://github.com/NickVolynkin/highload-2018/blob/master/2.1-vk-architecture.md
Тем временем, Лана Новикова на Highload провела и законспектировала митап про управление знаниями.
А ещё она уже некоторое время в тайне от всех ведёт канал про управление знаниями. Давайте сделаем тайное явным и вместе подпишемся на @the_know_all.
А ещё она уже некоторое время в тайне от всех ведёт канал про управление знаниями. Давайте сделаем тайное явным и вместе подпишемся на @the_know_all.
Forwarded from Knowledge and bacon - Управление знаниями в IT
Делюсь конспектом и слайдами с митапа Управление знаниями по принципам DevOps, очень продуктивная дискуссия получилась
https://gist.github.com/lananovikova10/1e19e169d7365b958b7a4d15491a6b00
https://gist.github.com/lananovikova10/1e19e169d7365b958b7a4d15491a6b00
Gist
Notes from Highload++ 2018
Notes from Highload++ 2018. GitHub Gist: instantly share code, notes, and snippets.
Монолит для сотен версий клиентов: как мы пишем и поддерживаем тесты.
Владимир Янц, Badoo
Снова доклад-ликбез про организацию тестирования в Badoo. Думаю, что это можно показывать начинающим разработчикам и тестировщикам, чтобы донести до них ценность тестирования и понимание пирамиды тестирования.
В конце слайдов были полезные ссылки от докладчика, я их скопировал в конспект.
https://github.com/NickVolynkin/highload-2018/blob/master/2.2-testing-badoo.md
Владимир Янц, Badoo
Снова доклад-ликбез про организацию тестирования в Badoo. Думаю, что это можно показывать начинающим разработчикам и тестировщикам, чтобы донести до них ценность тестирования и понимание пирамиды тестирования.
В конце слайдов были полезные ссылки от докладчика, я их скопировал в конспект.
https://github.com/NickVolynkin/highload-2018/blob/master/2.2-testing-badoo.md
Как устроить хайлоад на ровном месте.
Олег Бартунов, Федор Сигаев, Postgres Professional
Олег и Фёдор подробно рассказывают, какие ошибки приведут вас к хайлоаду, деградации сервисов и тотальному аду. Часть ошибок — общие, часть специфичны для PostgreSQL.
Вот это для меня стало прямо-таки откровением: «Поисковые системы лучше всего ищут в ночь с субботы на воскресенье. Когда нагрузки больше, они ограничивают задачу, чуть ухудшают качество, но зато не деградируют.»
А ещё Олегу дважды звонили по телефону, он поднимал трубку и говорил «я занят!». Я уже надеялся, что это постановка и в конце ему выкатят тележку как из супермаркета, полную звонящих телефонов — будет хайлоад. Но так не случилось.
Конспект на GitHub.
Олег Бартунов, Федор Сигаев, Postgres Professional
Олег и Фёдор подробно рассказывают, какие ошибки приведут вас к хайлоаду, деградации сервисов и тотальному аду. Часть ошибок — общие, часть специфичны для PostgreSQL.
Вот это для меня стало прямо-таки откровением: «Поисковые системы лучше всего ищут в ночь с субботы на воскресенье. Когда нагрузки больше, они ограничивают задачу, чуть ухудшают качество, но зато не деградируют.»
А ещё Олегу дважды звонили по телефону, он поднимал трубку и говорил «я занят!». Я уже надеялся, что это постановка и в конце ему выкатят тележку как из супермаркета, полную звонящих телефонов — будет хайлоад. Но так не случилось.
Конспект на GitHub.
Как стать классным спецом по базам данных
Илья Космодемьянский, Data Egret
Карта местности, маршрут, список достопримечательностей и рекомендации опытного путешественника. Лично меня порадовало, что Илья рекомендует вместо книг привыкать читать документацию:
— хороших книг по практике мало,
— и они недолго остаются актуальными.
А ещё Илья рекомендует будущим DBA общаться с разработчиками и нести им знания о БД, чтобы они лучше понимали и делали меньше ошибок. Вот буквально так:
— учиться говорить, писать и читать по-русски и по-английски;
— делать доклады, выступать на митапах и подаваться на Highload.
Конспект: https://github.com/NickVolynkin/highload-2018/blob/master/2.4-dababase-pro.md
#highload2018 #highload
Илья Космодемьянский, 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.
#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'е. Мы будем точно такие — в белых халатах, с табличками и с умным выражением лица.
В этом году мы с коллегами из сообщества техписателей уже дважды приходили на конференции со стендом Documentation Doctors. К нам приходят с вопросами о том, почему никто не пишет документацию, почему никто её не читает, как задокументировать легаси без исходного кода и как писать case-study, чтобы было понятно инвесторам из долины.
23-25 ноября мы отправляемся на ещё одну конференцию — DevFest Siberia 2018. Все три дня будем общаться с вами на стенде, наверняка ещё устроим митап. Приходите просто поговорить или порешать конкретные проблемы с вашими доками.
Вот фото, чтобы вы нас узнали на DevFest'е. Мы будем точно такие — в белых халатах, с табличками и с умным выражением лица.
Ещё 4 конспекта Highoad++.
Эксперимент с конспектированием Highload++ в целом прошёл удачно. На выходных законспектирую ещё 3-4 доклада, а потом напишу краткий отчёт по эксперименту.
Порекомендуйте, что стоит посмотреть? Какие доклады были самые огненные, самые полезные? Пишите мне личным сообщением (@nick_volynkin) или в @docsascode.
Эксперимент с конспектированием Highload++ в целом прошёл удачно. На выходных законспектирую ещё 3-4 доклада, а потом напишу краткий отчёт по эксперименту.
Порекомендуйте, что стоит посмотреть? Какие доклады были самые огненные, самые полезные? Пишите мне личным сообщением (@nick_volynkin) или в @docsascode.
Зачем выделять внутристрочный код.
Это спонсорский пост. Боль и гнев для его написания предоставлены документацией OASIS.
Если документация рассказывает о программном коде, то все фрагменты кода должны быть отличимы от обычного текста. Для этого код внутри абзацев форматируют стилем «внутристрочный код» (inline code,
А если так не делать, то читатель будет думать, что же такое «именейшие и именоватые атрибуты»:
Это спонсорский пост. Боль и гнев для его написания предоставлены документацией OASIS.
Если документация рассказывает о программном коде, то все фрагменты кода должны быть отличимы от обычного текста. Для этого код внутри абзацев форматируют стилем «внутристрочный код» (inline code,
вот так). Это очень помогает читать и понимать текст.А если так не делать, то читатель будет думать, что же такое «именейшие и именоватые атрибуты»: