​​Почему важна SRE-документация
#seeking_sre #sre

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

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

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

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

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

Образцы для документирования кода.

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

Вот почему это отличный источник примеров:
— Разработчики самого языка старались сделать основы языка максимально понятными; они вложили в этот код и текст много труда.
— Разработчики, которые пишут на этом языке, сотню раз читали документацию к стандартной библиотеке. Они привыкли к виду и стилю этой документации. Если вы напишете примерно так же, вы сделаете им удобно.

Руководства по Javadoc.

Дополнение к посту про документирование кода. Вот пара хороших руководств о том, как документировать код на Java:

— How to Write Doc Comments for the Javadoc Tool

— Advanced Javadoc Guidelines.

Спасибо @annacraneo за ссылки!

​​It sounds like I wrote it.
Поделюсь с вами приятным. Пользователь хвалит наш changelog очередной версии WordPress Toolkit:
Has anyone acctually read the changelog? It is absolutely hilarious in places. “No longer fall on its face”, “weird and mysterious reasons”, etc. etc. It sounds like I wrote it. I fully approve! Big thumbs up.

А у вас такое бывает? Поделитесь в @docsascode.

Возможно, некоторые слышали или использовали такой замечательный инструмент как postman, так вот - его можно использовать для генерации документации https://medium.com/@olotintemitope/how-to-generate-your-api-documentation-in-20-minutes-4e0072f08b94  #api #postman

​​Ух ничего себе, вот это интерпретация. Ответ 42 — это *, то есть всё вообще, всё что угодно.

Картинку нашёл в ∏ρ؃uñçτØρ Øπτµç∑.

Прямо сейчас начинается митап про инструменты для разработки документации.

Вот программа:

• Алиса Комиссарова, архитектор контента Positive Technologies, расскажет о SCHEMA ST4
• Михаил Григорошенко, старший технический писатель «Лаборатории Касперского» — об AuthorIT.  
• Ксения Притула, ведущий технический писатель «Центра Финансовых Технологий» — о Help&Manual.
• Дина Мощина, технический писатель Positive Technologies — о Dr.Explain.
• Мария Смирнова, руководитель группы технических писателей OZON.ru — о Slate.

Трансляция митапа здесь: https://www.youtube.com/watch?v=NYUV0dY2hXk

Обсуждение в чате https://t.me/joinchat/BsNas1WmbaKf5Otcb6j6TQ

Метрики эффективности документации.

Совсем недавно Яндекс проводил митап про метрики эффективности документации. Были такие доклады:

— Методы оценки трудозатрат и сроков документирования или Как правильно отвечать на неправильные вопросы. Александр Лебедев, компания Философт.
— Как измерить качество документации и эффективность её разработки. Светлана Каюшина, Юрий Никулин и Антон Литвинов из Яндекса.
— Кастомизация отчётов, или Как говорить на языке метрик без переводчика. Анастасия Агеева, Intel.

Лана Новикова (@the_know_all) законспектировала доклады, там же есть ссылки на слайды. Ставьте звёзды, кидайте пуллреквесты с дополнениями:

https://github.com/lananovikova10/7-12-minihyperbaton.md/blob/master/conspectus.md

Организаторы обещали выложить видеозаписи в январе 2019.

​​Воронка технической сложности документа.
Прочитал статью про превью ссылок в Telegram. Статья хорошо выстроена по сложности и подаче материала.

Сначала смысл фичи объясняют как для ребёнка, буквально говорят, на какую кнопку нажать. А затем, от заголовка к заголовку, техническая сложность статьи повышается, так что до следующего заголовка дочитает всё меньше читателей. Это можно назвать воронкой технической сложности документа. (Только что придумал термин. Если это уже как-то названо — скажите, я поправлю.)

В целеполагании технического документа есть основные вопросы: кто читатель, какова цель читателя, какова цель бизнеса. Я уже разбирал их на примере комикса про Kubernetes. Давайте посмотрим на каждую главу этой статьи и ответим на эти вопросы. Заметьте, как от заголовка к заголовку сужается аудитория, меняется цель читателя, но строго выдерживается цель бизнеса.  

Instant Views Explained  
Для новичков. Задача читателя — наверное, удовлетворить любопытство. Задача бизнеса — чтобы читатели пользовались instant view, читали статьи прямо в мессенджере и не уходили в браузер.

How does this work?  
Для тех, кто понимает основы интернета: ссылки, домены, шаблоны веб-сайтов. Задача читателя — понять, почему у одних сайтов есть instant view, а у других нет, и как сделать это для своего сайта. Задача бизнеса — замотивировать читателей делать шаблоны, чтобы instant view работал и пользователи не выходили из приложения.

Join buttons  
Для владельцев сайта и телеграм-канала одновременно. Читатель здесь узнаёт, что в instant view можно добавить ссылку для подписки на канал в один клик. Задача бизнеса — ещё больше замотивировать читателей. Вот меня замотивировали. Конверсия? Конечно, хочу. Займусь сайтом — точно сделаю себе шаблон и ссылку для подписки на @docops.

Instant View Editor  
Для тех, кто хочет и может сделать шаблон для сайта. Задача читателя — понять, насколько это сложно, какие есть инструменты. Задача бизнеса — облегчить вход в разработку шаблонов.

Templates tutorial  
Для тех, кто прочитал прошлую главу и решился делать. Задачи читателя — написать первый шаблон. Задача бизнеса — получить ещё один шаблон.

И наконец, в конце статьи — переход к документации разработчика. Там сразу начнётся хардкорный справочник по формату данных в шаблонах. Дойдут в основном те, кто осилил tutorial. А остальным и незачем это видеть.

You're now ready to move on! Знаете другие примеры хорошей документации? Или вам больно от очень плохой документации? Присылайте примеры @nick_volynkin или в чат @docsascode.

Хе-хе. Я так же удивляюсь про разработчиков на низкоуровневых языках. Просто у каждого своя специализация. Давайте сотрудничать и помогать друг другу. :)

https://t.me/extern_world/115

Architectural Decision Record.
В любом продукте бывают важные решения: на каком языке писать, делать монолит или микросервисы, использовать табы или пробелы, чёрную тему редактора или белую. Продукт растёт, решения копятся. В какой-то момент разработчик Х смотрит на решение Y и удивляется, почему всё сделано именно так.

Расскажите, а как вы сохраняете знания о том, кто, как и почему принял конкретное архитектурное решение?

🤦‍ — Никак. Говорим, что так исторически сложилось.
😇 — Все решения помнит архитектор проекта.
🤖 — Объясняем прямо в коде, там же ищем ответы.
📄 — Записываем решение при постановке задачи.
📘 — Пишем отдельную архитектурную документацию.
🔥 — Ведём журнал архитектурных решений по четкому шаблону, например ADR.

Приходите к нам в чат, мы вам хорошего посоветуем. 🙂

В чате https://t.me/docsascode пару недель назад увидела рекомендацию notion.so. Это простая система управления знаниями. Сами разработчики говорят о ней, как о "все в одном". И это действительно так - есть иерархия, календари, канбан-доски и простой редактор текстов.

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

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

​​Новый конспект Highload.

Тут случилось почти невероятное. В репозиторий с конспектами Highload закинули целых три пулл-реквеста. Два — с исправлениями и дополениями. Спасибо за них Ивану Муратову и Никите Грызлову!

А вчера Ефим Поберёзкин (@efim_poberezkin) отправил третий — с целым конспектом доклада Andy Pavlo «Make Your Database Dream of Electric Sheep: Designing for Autonomous Operation». Особенно круто, что доклад и конспект — на английском.

Если у вас тоже есть конспекты — будет здорово, если вы тоже их добавите. Так они принесут пользу ещё множеству людей. Так уж получилось, что этот репозиторий много читают, и ваш конспект тоже будут читать. Смотрите сами, на скриншоте Insights → Traffic с гитхаба.

Ruby code documentation.

Друзья-рубисты, а расскажите, как вы документируете код? Чем лучше сгенерить красивый и удобный сайт с документацией по коду? А ещё,  как писать комментарии к методам, чтобы среда разработки их понимала и показывала? У меня IDEA c плагином Ruby, но могу поставить RubyMine.

Задача такая: есть немного кода на Ruby, я его сейчас понял, а через месяц снова забуду. Хочу грамотно написать комментарии в коде (это план-минимум) и сгенерить сайтик с документацией (это план-максимум).

Похоже, что официальная документация сделана на RDoc, но она какая-то несимпатичная, простите уж. Ещё есть YARD, и ruby-doc.org хорошо выглядит, но неясно, чем сгенерили.

В общем, расскажите, что самое лучшее, правильное и удобное? Приходите в @docsascode или в личку @nick_volynkin.

Your Career опубликовали исследование рынка труда в ИТ. Подробно: https://t.me/yourcareer/618

Кратко про технических писателей: в Москве до 4 лет опыта в среднем 80к, дальше 145к; в Питере соответственно 65к и 100к. Это гросс, до налогов.

А у вас как?
👍 — выше средней
👌 — средняя
👎 — ниже средней
😂 — я дата-сатанист, получаю столько же в евро

​​Предложенные правки в мерж-реквестах GitLab.

Совсем недавно вышел новый GitLab 11.6. В нём есть интересная фича: теперь в мерж-реквестах ревьюер может предлагать изменения. Потом автор реквеста одной кнопкой принимает эти изменения, они становятся новым коммитом.

Думаю, эта фича будет очень полезна в работе с текстом. Мы уже привыкли работать с предложенными правками в Google Docs и похожих инструментах. Редактор не пишет «думаю, здесь лучше написать вот так-то». Редактор просто выделяет старое и поверх него пишет новое, предложенной правкой. Это удобно, и теперь это есть в GitLab.

Обязательно попробую эту штуку сам — я как раз пошёл на учебный курс и сдаю задания куратору в GitLab. Расскажу потом, что получится. А вам как? Будете использовать предложенные правки для ревью документации и/или кода?

🔥 — выглядит интересно, иду пробовать.
🌳 — мне достаточно комментариев.
💨 — у меня Word/CMS/ревью-по-электропочте, так что без шансов.
❄️ — а зачем ревью и мерж-реквесты? Я сразу пишу идеальный код/текст.

Ошибочка вышла.
Кстати, заметьте, что на картинке выше предлагают заменить валидный код на невалидный:
<p>... </p1>
Пасхалка или небрежность автора?

Технический писатель 2.0.1.

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

Думаю, что доход профессионала пропорционален пользе для бизнеса. Ещё влияют навыки переговоров, зрелость компании, рынок и прочее. Но умение создавать полезный результат и объяснять его полезность — это главное.

Как приносить больше пользы с помощью документации и текста вообще? Как измерить эту пользу? У меня есть доклад как раз об этом: «Технический писатель 2.0.1» Рассказываю про пять нестандартных ролей, их типичные задачи и точки измерения результата:

— DocOps-инженер
— UX-писатель
— Технический евангелист
— Knowledge manager
— Documentation owner

Доклад версионный: я общаюсь с новыми людьми, получаю обратную связь, дорабатываю доклад и рассказываю снова. Пока что было две итерации, так что версия приросла с 2.0 до 2.0.1. Вот запись второго выступления на митапе Write the Docs Moscow #2: Технический писатель 2.0.1.

Очень хочу обратной связи, критики, дополнений и ваших историй успеха в работе с текстом и знанием. Расскажите мне, какие задачи вы решаете, в чём приносите пользу, и как её измеряете. Пишите @nick_volynkin.

А ещё я буду вам очень благодарен, если вы подпишетесь на канал Write the Docs Russia. Сейчас там 13 подписчиков. Будет 100 — у канала появится понятный URL.