Митап 22 августа в Москве: запись, время, доклады

22 августа мы проведем документационный митап в Москве. Поговорим о документации и управлении знаниями в IT-компаниях. Формат — несколько докладов на 10-15 минут, вопросы докладчикам и свободное общение.

Вот, что важно сделать сейчас:

0. Подайте заявку на доклад, если вам есть, о чём рассказать. Готовить доклад за неделю сложно, но мы с коллегами постараемся вам помочь.

1. Запишитесь на meetup.com, чтобы вам хватило места. В помещение войдёт человек 40.

2. Отметьте, когда вам удобно начать митап. Точное время выберу и объявлю в четверг, 16 августа.

3. Возьмите паспорт или другое удостоверение личности, чтобы пройти в здание.

Трансляции не будет, зато будут конспекты и слайды. Все новости буду публиковать в канал @docops.

Обсуждение и планы — в чате @docsascode.

​​Сайт etsy.com прямо сейчас закрыт на техобслуживание. Посмотрите, какую классную страницу они сделали, чтобы рассказать пользователям, почему сайт недоступен:

​​За что я не люблю 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):