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

Дмитрий Лишик, Системный подход к техническим коммуникациям.

https://youtu.be/g_YjFnkcjgo

Консистентность-2

Снова про задачу о неконсистентном тексте.   Смотрите, какая штука происходит с кнопками в интерфейсе. Их можно:
 
— нажимать: «Clicking on Metrics...»
— или выбирать: «then select Monitorings button»

Фактической разницы нет. Просто одно и то же нажатие на кнопку в соседних абзацах называется по-разному.

Во втором и третьем абзаце есть такие сущности:

— Рабочие окружения (environments): production и другие.
— Метрики производительности приложения, которое развёрнуто в конкретном окружении (application performance metrics).

Всё идёт хорошо, пока в последнем предложении не появляются «production metrics». Автор текста взял и сделал новый термин из двух старых. Что этот новый термин обозначает? Кажется, что это метрики приложения, развёрнутого в окружении с именем production, но полной уверенности у меня нет.

К счастью, всё последнее предложение — маркетинговый буллшит, а смысл фичи ясен из предыдущего текста. Было бы хуже, если бы от точного смысла этого предложения зависела моя или ваша работа.

Чтобы такого не было, используйте термины консистентно:

Для каждой сущности — свой термин. Каждый термин — только для одной сущности.

Неконсистентное использование click-select первым заметил @glu0n. Ещё несколько человек писали мне об этих и других проблемах текста. Кое-кто сразу переписал текст в довольно приятном и понятном стиле. Спасибо всем, кто откликнулся! Очень ценю ваш вклад.

Как выстроить разработку внутренней документации

Игорь @i_tsupko спрашивает в чате @docsascode:

Проблема: есть пара-тройка человек, которые пополняют внутреннюю базу знаний. И каждый тянет одеяло на себя, не могут договориться о том как структурировать доки, как делать меню, навигацию и прочее.

Как договориться? В программировании для этого есть фреймворки и паттерны. А с русским языком как быть? Он ж не компилируется и автотесты не напишешь.

Что важно в документации:

— Структура и читаемость — чтобы юзер мог это брать и юзать на своем уровне компетенций.  
— Ненагруженный, неформальный язык и минимум формализма.  
— Важнее наличие хотя бы паршивой, верхнеуровневой, но хорошо структурированной доки (а-ля вот эта задача решается примерно по таким шагам, копать туды) но раньше, чем хорошо проработанной, но позже.  
— Важно, чтобы дока внедрялась и юзалась. Важнее всего и даже текста.

У вас тоже это болит? Знаете решение? Приходите в @docsascode, обсудим.

Внутренняя документация с картинками и разграничением доступа

Дарья (@Greenochre, канал @pmwithloveandsqualor) ищет инструмент для внутренней документации:

В чем уместно вести внутреннюю документацию для анимационной студии? Джиры и конфлюэнса у нас нет; кода нет тоже))

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

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

Что есть лучше гуглдоков, желательно бесплатное и с аналогичной регулировкой уровней доступа?

Помогите Дарье найти, в чём писать документацию!

Как обычно, приглашаю поделиться идеями в t.me/docsascode.

Публикация из AsciiDoc в PDF по ГОСТ

Компания Course сдаёт отчётную документацию в PDF со строгими требованиями к оформлению, потому что работает с банками и государственными заказчиками. При этом:

— Документацию разрабатывают в формате разметки AsciiDoc, со всеми преимуществами подхода «документация как код»: пишут в удобном редакторе, версионируют в Git, легко объединяют изменения от нескольких авторов. (Попробуйте-ка заняться этим в Word.)

— Большáя часть документации автоматически генерируется из программного кода: структура БД, описание REST API сервисов, частично ПМИ и результаты автоматизированного тестирования по ПМИ.

Как получилось совместить ГОСТ и документацию как код? Николай Поташников, автор той самой статьи про диаграммы как код в PlantUML, разработал шаблон для публикации из AsciiDoc в PDF со всеми требованиями к оформлению.

Вот исходный код и документация к шаблону: github.com/CourseOrchestra/course-doc

Николай хочет дорабатывать и улучшать этот шаблон, чтобы и другие компании могли отказаться от неудобных редакторов в пользу AsciiDoc. Нужна обратная связь. Если вы используете AsciiDoc — пожалуйста, протестируйте шаблон и напишите о результатах в чат @docsascode, либо автору на  @nmpotashnikoff или nm@potashnikoff.net.

#docops_toolkit #docops_markups #docops_gost

Deboogging Loceleezeshoon!

Копаюсь в Translate Toolkit, нашёл инструмент для дебага локализации, он «понарошку» переводит строки. Среди вариантов есть псевдо-шведский, вдохновлённый персонажем Маппет-шоу Swedish Chef. Вот что получается:

Introdoocteeon

This gooide-a describes how to troonsffer hosted content to Plesk Oonyx using Plesk Migretor. Bork Bork Bork! It is intended for hosting idministretors who perfform migreshoon to serfers mooneged fia Plesk. Bork Bork Bork!

Whet Deta Ire-a Troonsfferred

Plesk Migretor troonsffers serfice-a ploons, soobscripshoons wit ill issocieted domeins, und websites wit content (sooch is files, meil, detebeses, und so oon). Reseller und coostomer iccooonts zeet do not hefe-a uny domeins ire-a not troonsfferred. Bork Bork Bork! Zee-a settings ooff Plesk serfices, sooch is instelled PHP hoondlers, Feeel2Boon settings, ModSecoority settings, foorooell settings, und so oon ire-a not troonsfferred. Bork Bork Bork!

Сравните с оригиналом: Plesk Migration Guide – Introduction.

Дебаггер работает с файлами в формате GNU Gettext (.po):

podebug --rewrite chef source.po chef.po

#docops_l10n

​​Как подумать и написать обо всём, что важно

Представьте, что мы с вами придумываем новую фичу и пишем о ней документ (vision, SRS, ТЗ). Именно по этому документу дизайнеры придумают интерфейс, разработчики напишут код, а тестировщики проверят, всё ли получилось правильно.

Нам нужно обдумать и описать несколько аспектов фичи: интерфейс, безопасность, GDPR и другие. Держать всё это в голове довольно сложно.

Кажется, что задачу можно упростить шаблоном документа с заголовками секций про каждый аспект. Но бывает, что для фичи X неактуален аспект Y. Например, она не меняет интерфейс. Что тогда делать с заголовком из шаблона?

✘ Удалить заголовок. Читатель не поймёт, забыл автор про это написать или сознательно убрал.
✘ Оставить заголовок, ничего не писать. Так точно будет впечатление, что автор забыл.
✘ Оставить заголовок и написать «Это неприменимо или не имеет значения для этой фичи». Это засоряет документ и усложняет работу читателя.

Все варианты плохи. Ещё сложнее делегировать разработку фич и написание таких документов. Тогда мы сами становимся непонимающими читателями.

Сергей Егоров, руководитель program manager'ов в Plesk, поделился решением:

В конец документа добавляем табличку-чеклист со списком аспектов. В ней ПМ отмечает каждый аспект: «Описано в документе» или «Неприменимо». Если неприменимо — заголовок можно убирать.  Если ничего не отмечено, значит ПМ ещё это не проработал.

✔ Отмечать в отдельном чеклисте: аспект описан / неприменим для этой фичи / конь не валялся.

#docops_workflow

Если вам нравится продумывать новые фичи и развивать продукты, в Plesk есть вакансия program manager'а в команду к Сергею Егорову, эксперту из прошлого поста про шаблон-чеклист документа.

Вопросы про вакансию и компанию в целом можно задавать мне на @Nick_Volynkin или nvolynkin@plesk.com.

Чеклисты и 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. При выходе из лифта поверните направо и сразу налево.