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

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

​​Почему важна 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://news.1rj.ru/str/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://news.1rj.ru/str/extern_world/115

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

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

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

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

В чате https://news.1rj.ru/str/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.