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

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

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

https://github.com/NickVolynkin/highload-2018/blob/master/2.2-testing-badoo.md
DocOps pinned «Привет, давайте знакомиться! Я работаю техническим писателем в Plesk, внедряю практику «документация как код», пишу в этом канале про документацию и управление знаниями, организую митапы на те же темы. Посты в канале обсуждают в чате @docsascode. Сегодня…»
Как устроить хайлоад на ровном месте.
Олег Бартунов, Федор Сигаев, 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, вот так). Это очень помогает читать и понимать текст.

А если так не делать, то читатель будет думать, что же такое «именейшие и именоватые атрибуты»:
​​Вот так гораздо лучше. Ещё термин выделим, это тоже не просто текст.
Максим Цепков конспектировал доклады про управление и организацию разработки. Максим вытаскивает самую суть, пишет связный и логичный текст, добавляет своё экспертное мнение и лог обсуждения с другими экспертами. Это очень круто, я теперь тоже буду стараться так писать.
Forwarded from Maxim Tsepkov
Собрал вместе свои посты с #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
Там ещё есть «Цель 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
​​Иногда документация бывает слишком минималистична:
​​Почему важна SRE-документация
#seeking_sre #sre

Недавно писал про главу о документации из книги Seeking SRE. Вот вам ещё одна статья по той же теме: Why SRE Documents Matter. Там целая история про джуна-SRE по имени Zoë (Зоуи). На основе этой истории автор приводит примеры и объясняет смысл. Люблю этот жанр учебной литературы: в нём написана Цель, Дедлайн и Проект Феникс.

Max Rokatansky из Отуса перевёл эту статью на русский язык:

— часть 1: введение в SRE и зачем там документация,

— часть 2: конретные виды документации, в чём их польза, как их писать.

Статей про документацию на Хабре маловато, хочу чтобы их было больше. Давайте мотивировать авторов. Вот например, вторая часть про доки SRE только вчера опубликована, ещё можно ставить плюсы. 😉
Образцы для документирования кода.

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

Вот почему это отличный источник примеров:
— Разработчики самого языка старались сделать основы языка максимально понятными; они вложили в этот код и текст много труда.
— Разработчики, которые пишут на этом языке, сотню раз читали документацию к стандартной библиотеке. Они привыкли к виду и стилю этой документации. Если вы напишете примерно так же, вы сделаете им удобно.
2025/07/09 16:39:16
Back to Top
HTML Embed Code: