​​Предложенные правки в мерж-реквестах 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.

— в этом разделе будут ваши споры
— на этой странице будут ваши штрафы
— в этом коде будут ваши баги

АААААААааааа!

t.me/theyforcedme/704

Хорошие новости, подарки и игра.

Привет, друзья! У меня есть для вас две хороших новости: конференция про управление знаниями и курс по DocOps. А ещё я приготовил для вас подарки и игру.

KnowledgeConf.
В конце апреля 2019 года в Москве пройдёт конференция про управление знаниями в IT. Будут доклады о том, как снижать риски, переиспользовать решения, улучшать автобусный фактор, быстрее онбордить новых сотрудников. Организует конференцию Олег Бунин, а автор этого канала работает в программном комитете.

Мы ищем докладчиков! Если хотите выступить, оставьте заявку на conf.ontico.ru. С любыми вопросами пишите мне (@nick_volynkin).

Курс по DocOps.
Я начал работу над курсом по DocOps. Буду выпускать его небольшими частями, которые потом соберу в одно целое. В курсе будут в том числе такие темы:

— документация как код, языки разметки и генераторы
— continuous delivery для документации
— линтеры и тесты для документации
— документирование API и SDK
— документирование инфраструктуры и микросервисов

Несколько модулей опробую в конце января на зимней студенческой школе в НГУ. Студенты научатся интересно писать о своих проектах, редактировать и деплоить сайты с документацией и делать презентации на reveal.js. Если вы студент — записывайтесь на школу, там классно.

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

Игра.
Лучший подарок для меня — когда вы даёте мне обратную связь и рассказываете друзьям про канал @docops. Давайте сыграем в игру. Сейчас здесь 974 читателя. Если к 1 февраля будет 1300, то после студенческой школы я повторю курс онлайн для всех желающих, бесплатно, в обмен на обратную связь.

С новым годом!

А для тех, кому понравится нравится писать хорошие конспекты, у меня будет отдельное деловое предложение. Присоединяйтесь. 😁

Питер, отзовись!
Мы делаем митап про разработку в формате Lean Coffee и ищем техписов, которые готовы помочь с конспектированием бесед.
Ссылка на мероприятие: https://piterpy.timepad.ru/event/886097/
Пример бомбового конспекта от @Nick_Volynkin: https://github.com/NickVolynkin/ritfest18-community-meetup

Кстати, завтра я выберу три лучших отзыва и подарю авторам хорошие книжки, которые и так всем рекомендую: Проект Феникс или Docs Like Code.

Хотите книгу? Ответьте на пару вопросов про этот канал и учебный курс.

​​Подарки за отзывы.

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

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

(нумерация с 2 по 25, потому что первым идёт заголовок таблицы)

Сергей Абдульманов о текстах в интерфейсе.

Конференция Dump-18 опубликовала записи докладов. Среди них есть доклад Сергея Абдульманова, директора по маркетингу компании Мосигра. Называется «Чем конкретно отличается понятный текст для интерфейса».

Сам ещё не успел посмотреть, скорее делюсь с вами. Ссылку увидел в @uxnotes, спасибо автору! 🙂

https://www.youtube.com/watch?v=XrhxisJN_zQ

​​Семён Факторович рассказывает про документацию студентам на CompTech NSK в Новосибирском государственном университете.

REST API.

Вчера вышла статья про то, как проектировать и документировать REST API, при этом не изобретая велосипеды. Автор рассказывает про типичные ошибки проектирования, про стандарты с лучшими практиками и про инструменты, которые реализуют эти стандарты. Остаётся взять и сделать себе хороший API.

https://habr.com/ru/company/oleg-bunin/blog/433322/

PagerDuty Incident Response

PagerDuty выложили в открытый доступ свою внутреннюю документацию по работе с инцидентами.

https://response.pagerduty.com

Postmortems

PagerDuty продолжают выкладывать внутреннюю доку, на этот раз про постмортемы.

https://postmortems.pagerduty.com

KnowledgeConf.

Почему в канале почти нет постов? Потому что автор работает в программном комитете конференции knowledgeconf.ru по вечерам после основной работы. На это уходят почти все силы. Зато у нас будет отличная конференция. Я вам позже буду рассказывать про доклады, которые мы приняли.

А пока что Света Новикова написала на Хабр про конференцию и нашу команду. Там много текста по теме и смешные случайные факты про ПК.

https://habr.com/ru/company/oleg-bunin/blog/437768/

Да что же такое, PDF мешает нашему мэру строить метро. Я готов стать личным советником Локтя по использованию Pandoc. Сделаем этим бюрократам .epub или что они там требуют.

​​There's no step two.
githistory.xyz — хороший инструмент для гита с великолепной инструкцией:

Quickly browse the history of any GitHub file:

1. Replace github.com with github.githistory.xyz in any file url
2. There's no step two

И гифка, чтобы совсем всё стало понятно:

​​I wanna tell my secret now. I see outdated documentation.