​​За что я не люблю WYSIWYG-редакторы.

Пишу документ в одном популярном инструменте с WYSIWYG-редактором.
Получаю список с неконсистентным интерлиньяжем (расстоянием между строками):

— В пункте списка «Три Четыре» я перенёс строку с помощью Shift + Enter. У него стандартный интерлиньяж.
— Пункт «Пять Шесть» я вставил с помощью Ctrl + V. У него увеличенный интерлиньяж.
— Других способов поменять интерлиньяж в списке я не нашёл.

Вывод: там внутри немного разный XML получается в каждом из этих способов. Просто внутренняя логика кода идёт разными путями и производит разную структуру. Редактировать эту структуру напрямую никак нельзя.

Получается, что отображение текста зависит не от его структуры и смысла, а от того, в каком порядке я писал исходник.

WYSIWYG, часть 2

Вчера я ошибся: внутреннюю структуру в Confluence можно просматривать и редактировать, есть специальная кнопка.

А теперь (читайте голосом Николая Дроздова) давайте заглянем внутрь редактора и посмотрим, что там происходит.

Если вставить в список две строки-параграфа (<p>Пять</p><p>Шесть</p>), как я делал вчера, в результате получается элемент списка с параграфом и обычным текстом:

<ul>
  <li>Раз<br/>Два</li>
  <li>Три<br/>Четыре</li>
  <li>
    <p>Пять</p>Шесть</li>
</ul>

А если вставить один параграф с переносом строки через Shift+Enter (<p>Пять<br/>Шесть</p>), получается элемент списка из двух параграфов:

<ul>
  <li>Раз<br/>Два</li>
  <li>Три<br/>Четыре</li>
  <li>
    <p>Пять</p>
    <p>Шесть</p>
  </li>
</ul>

Очевидно, тут баг. Из двух <p> получается один, а из одного с переносом — два. Хорошо, что мы можем исправить это вручную. Плохо, что мы вообще должны об этом заботиться.

Пойду писать багрепорт.

P.S. Почему я написал этот пост в три сообщения, а не в одно? А потому что Телеграм или мой бот для постов некорректно отображают текст в Markdown после блока кода. Приходится разбивать.

Вывод: WYSIWYG не фатально плох, а легковесные языки разметки — не панацея. Баги есть везде.

​​Митап сегодня в 19:00.
Прямо сегодня в Москве пройдёт митап про документацию и управление знаниями. Будут четыре небольших доклада и свободное общение.

Эксперты расскажут:
— Как писать документацию проще и понятнее.
— Что делать руководителю, чтобы разработчики сами писали и читали документацию.
— Про непрерывную локализацию интерфейса и документации на N языков.
— Как писать как код и генерировать из кода документацию по ГОСТ с переиспользованием содержимого и для M заказчиков.

Как принять участие:
1. Зарегистрируйтесь на meetup.com. Адрес и карта там же.
2. Возьмите паспорт, чтобы вас пропустили в здание.
3. Приходите немного заранее, успеем познакомиться.

Все вопросы задавайте в чате @docsascode.

Для тех, кто не сможет прийти:
— Конспекты и слайды будут в канале @docops.
— Запись докладов пока не планируем, но шанс есть.

Если вы можете принести оборудование для записи — напишите мне на @nick_volynkin.

На фото — дождливый Новосибирский аэропорт, из которого я к вам лечу. А сейчас я подлетаю к Москве, а робот публикует этот пост. Слава роботам!

Как добраться до митапа.

Митап пройдет в офисе компании «БИЗон» в бизнес-центре Melnikoff House по адресу улица Ольховская, дом 4, корпус 2.
Добраться до офиса на общественном транспорте проще всего от станций метро
Красносельская и Комсомольская.

От м. Красносельская:
1. Выйдите на улицу Нижняя Красносельская.
2. Идите все время прямо и пересеките мост.
3. Поверните на улицу Ольховская.
4. Здание бизнес-центра будет по левой стороне.
5. Нужный корпус легко узнать по большой надписи «На работу с радостью».

От м. Комсомольская Сокольнической линии:
1. Пройдите через здание Казанского вокзала к выходу на Новорязанскую улицу.
2. Поверните налево.
3. Идите прямо до поворота на Ольховскую улицу.
4. Здание бизнес-центра будет по правой стороне.
5. Нужный корпус легко узнать по большой надписи «На работу с радостью».

В здании:
1. На ресепшен предъявите документ, удостоверяющий личность, и сообщите, что
вы направляетесь в компанию «БИЗон».
2. Получите пропуск.
3. Поднимитесь на 2-й этаж.
4. При выходе из лифта поверните направо и сразу налево.

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

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

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

Подклчайтесь: 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”

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