Чеклисты и defensive writing

Из разговора с Сергеем Егоровым вынес ещё одну идею. Когда результат в 99% случаев положительный, люди забывают действительно проверять его и ставят галочку в чеклисте в 100% случаев.

Есть понятие «defensive programming» — когда мы пишем код так, чтобы приложение было устойчиво к ошибкам и непредвиденным обстоятельствам.

Давайте подумаем про «defensive writing». Как сделать текст устойчивым к ошибкам и искажениям человеческого восприятия? В частности, как защититься от привычки ставить галочку, не проверяя?

Вот пара идей:

— Сделать колонки «да» и «нет», чтобы подумать и отметить осознанно.
— Переформулировать из состояния в действие. Например, состояние — «окно закрыто», а действие — «я подёргал и убедился, что окно закрыто».

А как вы пишете чеклисты? Как бы вы решили эту проблему? Приглашаю поделиться идеями в @docsascode.

#docops_workflow #docops_defensive_writing

Решение для чеклистов от Ильи Улеско:

— В пунктах чеклиста нет по умолчанию выбранного варианта.
— Варианты ответа кодируются цветом.

У меня в ячейках таблицы чеклиста почти всегда располагаются выпадающие списки с значениями. Если критерий не проверен, то ячейка пуста (не выбрано значение из списка). Если критерий был обработан, то ставится значение согласно ситуации. Например, у критерия "актуальность" для страницы справки могут быть такие варианты:
- Актуальна (зелёная подсветка строки)
- Устарели скриншоты (оранжевая подсветка строки)
- Устарело содержимое (оранжевая подсветка строки)
- Требуется редизайн (красная подсветка строки)
- Полностью устарела (красная подсветка строки)

В итоге получается "светофор" на каждый критерий страницы - сразу наглядно видно, какие страницы с проблемами + насколько это критично.

Встреча в Москве 22 августа

Друзья и коллеги, 22 августа я буду в Москве. Прилечу в 9 часов утра.

Если нам есть, что обсудить, напишите мне на @Nick_Volynkin.

Я охотно поговорю про документацию. Мои любимые темы:
— внедрение docs as code,
— документация как продукт и сервис,
— документирование микросервисной архитектуры.

Можем даже организовать спонтанный митап. Если у вас есть идеи и/или помещение — пишите на @Nick_Volynkin!

Митап 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.