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

Если вас это отвлекает, пожалуйста, выключите уведомления в канале. В воскресенье поток закончится, сможете всё сразу прочитать.

Трансляция и запись митапа будет!

Подклчайтесь: https://www.youtube.com/watch?v=UMEDdvUNRAQ

Начнём в 19:00 по Москве.

​​Никита Соболев рассказывает, что компания we make services запрещает разработчикам общаться по работе не в документации, зато платит за её написание. 😱

​​Наталья Павликова из Xsolla рассказывает об опыте внедрения непрерывной локализации.

​​Николай Поташников знает, как вылезти из трясины MS Word.

​​Выкладываю оставшиеся фото с митапа. Вот Марк Шевченко, первый докладчик. Не успел сфотографировать его во время доклада, но успел после.

​​Спасибо вам, что пришли! В пике нас было 28 человек. Вот мы все вместе. Качество фото не очень, но посмотрите, какие мы сами классные!

Злой рецензент

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

Придётся через буфер обмена ставить скобку. :-

100 лет дизайна.

Посмотрел фильм 100 лет дизайна. Первая мысль: дизайнеры знают историю своей профессии, умеют рассказывать о ней, доносить её пользу и важность.

Вот я себя считаю сразу разработчиком и техписателем. Поэтому задаю себе один вопрос дважды: «А мы-то что? Мы знаем историю своей профессии? Мы понимаем, в чем её роль и значение в культуре? Рассказать о ней можем?»

Слайды с митапа в Москве

Слайды докладов с митапа про документацию, который прошёл в Москве 22 августа:

1. «Элементы стиля. Как писать технические тексты». Марк Шевченко, Московский клуб программистов.

2. «Continuous Documentation». Никита Соболев, We Make Services.

3. «Локализуем всё: 20+ проектов, 21+ язык, срок вчера». Наталья Павликова, Xsolla.

4. «Почему мы выбрали Asciidoctor для ведения программной документации». Николай Поташников, ООО «КУРС-ИТ».

Спасибо всем участникам, которые были с нами и смотрели трансляцию!

Пожалуйста, оставьте отзыв о митапе. Этим вы очень поможете нам сделать следующий митап ещё лучше.

Тем временем, мы уже планируем следующие митапы. Оставьте заявку, если хотите выступить.

​​Тексты в интерфейсе.

Тексты в интерфейсе должен писать или хотя бы проверять специальный человек, который специализируется на текстах. Это отдельная задача, которую нужно внедрить в рабочий процесс.

Иначе получаются банкомыты и прочие нелепости (скриншот Артёма Семёнова @savoptik):

​​Тексты в интерфейсе-2.

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

На практике это сложно, есть много подводных камней, придётся договариваться с людьми, доносить до них ценность хорошего UI-текста, менять процессы, переучиваться и переучивать.

Мы сейчас проходим этот путь в Plesk. У продукта два десятка лет истории, интерфейсных текстов очень много, есть с чем поработать. Результатами буду делиться с вами.

​​«Иди в технические писатели», — говорили они...

Мария Байкова (instagram.com/stelleries) нарисовала отличную иллюстрацию о работе технического писателя.

У компаний, особенно небольших, практикующих Agile, очень часто присутствуют проблема с документированием продукта и процессов.

Это распространенная болячка, и в интернете очень много разных How-To о том, как это решать.
Хуже, когда люди ссылаются на Agile Manifesto, дескать, работающий софт важнее документации.

Позволю себе процитировать Манифест: “Working software over comprehensive documentation”

Все, в целом, верно. Вот только речь идет о проектной документации, а не продуктовой или технической.

​​Подкаст Art of Programming про документацию

Выпуск подкаста «Art of Programming» про техническую документацию в Plesk и вообще. Ведущий — Антон «Голодный» Черноусов, в гостях я и мой коллега  из Plesk, Java-разработчик Денис Горбатых.

http://blog.golodnyj.ru/2018/09/171-art-of-programming-highload.html?m=1

На фото мы заняли переговорку наших HR'ов и готовимся к записи.

Смотрите, какие классные обложки у выпусков подкаста:
https://twitter.com/golodnyj/status/1037889400590540800

Новости с Write The Docs Prague 2018

Сегодня проходит Writing Day.

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

Обсуждаются такие темы:

1. Migrating docs to another tool
2. Blogs
3. Generatin Flare Snypets with Python
4. Extracting labels from source code to use as variables in Flare
5. MDN web DOCS
6. How to incentivise devs to write the docs?
7. Documenting CI/CD Cloud-based software
8. API Docs (Slate & other SSGs)
9. Write your own docs/Docs strategy
10. Guidelines for writing the Best online Documentation and building website for it
11. Rewrite the content (JetBrains)

​​Don't say “simply”, Jim Fisher

Джим Фишер рассказывает, почему не стоит писать слово «просто» в интерфейсе и доках.

Пример: чтобы установить приложение в macOS, нужно «просто перетащить» иконку приложения на ярлык «Applications». Но Джим понял это далеко не сразу. Как он говорит, — «действительно, это настолько „просто“, что разработчик специально написал, что это просто».

Идея: мы путаем «ease», лёгкость, и «simplicity», простоту. Пользователю становится просто, когда он уже освоил кучу требуемых концептов. Слово «simply» описывает действия, но не концепты.

Полный конспект доклада: https://github.com/NickVolynkin/wtd-prague-2018/blob/master/dont-say-simply.md

Программа Гипербатона.

Организаторы опубликовали программу Шестого Гипéрбатона.

Участие бесплатное, но по приглашениям. Чтобы получить приглашение, зарегистрируйтесь на сайте.

Темы:

— Текст как данные: автоматизируем формирование контента.
— Контент-стратегия: новый уровень экспертизы.
— Новый взгляд на документирование API и SDK в Яндексе.
— Машинный перевод: опыт Яндекса.
— Ландшафт сервисов облачного машинного перевода.
— Как работают разные инструменты автоматизации перевода и как их выбирать.

Доклад бывшего коллеги на DevOpsDays Moscow про то, как эксплуатации жить с сервисами - https://www.youtube.com/watch?v=j9I4oeEXBO8

Все боли очень знакомые:

- нет документации ("Если документации нет - значит никто не скажет, что она плохая!"),

- сервис передали другой команде и теперь там никто не знает, что с ним делать,

- уволился менеджер, который знал как там все должно было работать,

- партизанская разработка ("мы тут быстренько что-то сделали и оно уже приносит деньги!")

-сервис написали аутсорсеры, его приняли и теперь надо как-то с ним жить дальше.

И решения тоже понятные, знакомые и очевидные. Документация, регламенты, передача знаний внутри компании.

Но вот в реальной жизни это все раз от раза не работает(