Красивый номер мердж-реквеста у меня сегодня получился.

Как изобразить мэппинг (маппинг, mapping) данных в разных системах (источниках)

В этом посте под мэппингом понимается это соотношение между данными, которые находятся в разных системах.

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

А какими инструментами можно это делать?
Вариантов масса. Хочешь — рисуй руками. А хочешь — кодом. Мне ближе второй вариант. Про него расскажу в одном из следующих постов.

НЛО прилетело, приглашение принесло

Решил я на днях побороть вселенскую несправедливость и стать автором на Хабре.
Не порядок ведь: писал на Хабр не раз, но было это всё для клиентов, а публикаций от своего имени не было (хотя зарегался там в 2016 году).

И вот свершилось. Пару дней дней назад добавил на Хабр статью по материалам моего доклада на TW Days#1, а сегодня после обеда ее выпустили из песочницы.
Вот, собственно, статья.

Теперь я официально «Захабренный» (только бы не заминусовали новичка).

Регулярки можно изображать в виде схем

И делается все без особых напрягов.

Вы знали об этом? Я — нет. И только недавно узнал.
А ведь очень удобно.

И готовый инструмент для такой задачи есть. Это — PlantUML.

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

Пример кода для схематического представления регулярки для проверки номера телефона, взятой отсюда (номер 3 в списке):

@startregex
title RegExp для проверки номера телефона

/^\+?(\d{1,3})?[- .]?\(?(?:\d{2,3})\)?[- .]?\d\d\d[- .]?\d\d\d\d$/
@endregex

Результат — на картинке.
Согласитесь, довольно удобно и просто читать такую схему.

Про мутации (нет, это не из постапокалиптических фильмов, а из API)

Доводилось ли вам слышать про мутации?
В контексте техписательства (и не только) мутация — это тип операции в GraphQL API, с помощью которой меняются данные на сервере: добавляются, изменяются и удаляются.

Если в HTTP API (или REST, с вашего позволения) используется четыре разных типа запроса (имеется ввиду их разделение по используемому HTTP-глаголу):

- POST,
- PUT,
- PATCH,
- DELETE.

то в GraphQL для этого всего есть один тип операции Mutation.

А как тогда определять, что делает та или иная мутация, создает что-то, изменяет или удаляет? Нейминг!!! Важно при проектировании GraphQL API (впрочем, как и проектировании любого другого API) называть операции понятными именами.

Например:

• createUser — понятно, что мутация будет создавать пользователя.
• updateProduct — очевидно, что такая мутация обновляет сведения о продукте.
• deleteFilm — видно, что мутация удаляет фильм.

Ну и прикрепляю картинку: так искусственный интеллект видит изображение на тему «Использование мутаций в GraphQL API».

IKIWISI: техписы тоже с этим встречаются

Есть у аналитиков аббревиатура IKIWISI, образованная от фразы, которую многие просто ненавидят. Это фраза «I’ll know it when I see it», что переводится как «Узнаю, когда увижу».

Обычно такое слышишь от заказчика, который толком не знает, чего он хочет: типа «Ты что-нибудь сделай, а том посмотрим, то ли это, что я хочу».

У техписов тоже такое случается частенько: приходит заказчик, просит сделать какой-то документ, но объяснить, что в нем должно быть, и как это должно выглядеть, не может. Так что, аббревиатура IKIWISI и нелюбовь к ней, я считаю, к техническим писателям тоже применимы. Ну и IKIWISI — это «родня» фразы «Без нормального ТЗ результат будет ХЗ».

Что скажете?

Умели же когда-то обложки привлекательные для книг делать

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

Ура!!! Я только что защитил дипломный проект!!!

8 месяцев обучения пролетели незаметно. И было это продуктивно.
Теперь я не только технический писатель, но и подробности позже.

Техпис не должен... Или рынок все порешает

Наверное, это холиварная тем, но все-таки.

Что-то в последнее время все чаще стали попадаться высказывания типа «Техпис не должен...». Как правило, они всплывают в обсуждениях вакансий.

У большего количества таких высказываний посыл такой: мол техпис не должен делать ничего, кроме как писать инструкции.

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

А вот я так не считаю. Я думаю, что техпис должен. Должен стремиться к тому, чтобы пощупать всё, попробовать всё, понабивать шишки обо всё.
Должен, но с оговоркой: если работодатель достойно за это платит (достойная оплата — это тема для отдельного разговора).

Почему техпис должен? Я считаю, что это полезно для него же в первую очередь. Я уверен, что востребованный на рынке технический писатель — это T-shape специалист. А как стать таким специалистом, если ты свято веришь в «Техпис не должен»?

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

Да, может быть, в идеальном мире технический писатель реально не должен ничего, кроме как сидеть в уголочке и тихонько писать свои инструкции. Но живем мы в мире реальном. И я считаю, что техпис еще много чего должен (при условии получения соответствующего поощрения от работодателя). А за тех, кто «не должен» рынок все сам порешает.

Что скажете?

🚢 Я в отпуске, поэтому пост с морем и корабликами. Ещё надумал серию постов про docs as code (про диаграммы, как код, если точнее). Не переключайтесь.

Техписа на них нет...

Увидел в лифте такие вот правила пользования.
И они мне сломали мозг. Попросил жену и детей посмотреть на это и сказать, что здесь не так.
И все трое, включая 10-летнего ребенка, указали на одну и ту же проблему (которую я тоже сразу увидел).
Как думаете, что смутило всех в этой картинке?

Долго не можете найти техписа? Возможно, вам нужно поменять рекрутера

За последний месяц я получил 16 предложений от разных компаний (работу, если что, пока не ищу, они просто сами на меня выходят).
Заметил одну вещь. Ну как заметил, я и ранее, когда занимался контентом для агентства IT-рекрутинга, об этом знал. Но думал, что сейчас все стало лучше.
А вот хрен. Ничего лучше не стало, и многие HRы и рекрутеры не хотят работать.

Почти каждому из написавших мне я задавал уточняющие вопросы по вакансии. Из 16 вакансий вопросов не возникло по 6 (там все было понятно и доходчиво расписано).
По десяти полученным предложениям были отправлены уточняющие вопросы (про вилку, стек, условия удалёнки и пр.). И только по трем была получена обратная связь. Остальные 7 HRов (или рекрутеров) просто молча отвалились. Естественно, когда они придут в следующий раз с предложениями, так же столкнутся с молчанием :) Я неверю, что они могут искать ответы на вопросы по 1-2 неделе, если что.

Вот вам и причина долгих поисков. Она на поверхности: кто-то на букву «Эйчар» или «Рекр» просто не хочет нормально работать.

Недавно в одном из каналов для бизнесменов рассматривался похожий кейс. Компания более полугода не могла найти сварщика. Когда начали разбираться, куда ж делись все сварщики, проанализировали критерии, по которым HR вела поиски (и чуть не поседели). Среди критериев там был возраст до 30 лет, амбициозность и … барабанная дробь … активность в Инсте (активность в Инсте сварщика, блеать!!!). За поиски взялся руководитель и нашел спеца за 3 дня.

Техписы, конечно, не сварщики, но подход к их поиску, как я погляжу, у некоторых примерно такой же — спустя рукава.

Удачи в поисках. И если они затянулись, бегите к HRу (рекрутеру) и смотрите, что и как он это делает.

Идентификатор ресурса в API. Когда его можно назвать хорошим

Идентификаторы (далее ID) позволяют однозначно идентифицировать (простите за тавтологию) конкретный объект (или ресурс API в нашем случае). И к их формированию не стоит подходить «спустя рукава»: хотя казалось бы, что там придумывать, просто взял и пронумеровал все (нот нет, не прокатит).
В разных источниках встречается от 5 до 8 атрибутов (или признаков), за счет которых ID можно назвать хорошим. Больше всего мне понравилось, как это сформулировал Д. Гивакс.
Он выделяет следующие атрибуты хороших идентификаторов ресурсов API:
1️⃣ Уникальность.
2️⃣ Непредсказуемость.
3️⃣ Простота использования.
4️⃣ Постоянство.
5️⃣ Быстрота и легкость генерации.
6️⃣ Читабельность.
7️⃣ Информационная плотность.

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

Кто хочет вкатиться в Docs as code? У моего коллеги в канале стартовал курс (бесплатный!!!!) для новичков.
Присоединяйтесь, Антон плохому не научит.

А не хотите мини-курс по документированию API?

Хочу сделать мини-курс по документированию HTTP API.
Но не совсем прям только по документированию.
Я вижу это все так:

1. Мы спроектируем свой API. Небольшой такой, буквально на несколько методов. Это позволит вам немного побыть в роли того, кто этим занимается, и в общих чертах понять, как это все происходит.
2. Далее мы создадим для этого API спецификацию в формате Open API. И это уже будет одним из видов документации.
3. Затем из полученной спецификации мы сгенерируем статический сайт-справочник. Для этого будем использовать Foliant. Возможно, попробуем и другие инструменты, чтобы почувствовать разницу.
4. Напишем доку вручную (как будто у нас нет Open API-спецификации) и снова генерируем сайт-справочник из всего этого.

И не хотелось бы, чтобы на этом все закончилось. Я думаю (не обещаю, но хотелось бы это реализовать), что мы замокаем API, либо развернем его с помощью специального сервиса, или же вообще сгенерируем код бэкенда и разместим все это дело где-нибудь. Потом «подергаем API-ручки», чтобы вы знали, с какой стороны подойти к API.

Как вам идея? Если этот пост наберет 30 сердечек ❤️ к исходу среды (18 сентября), мини-курсу быть, не наберет — ну и фиг с ним, с этим курсом.

Все будет происходить здесь, в этом канале.

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

Дожидаться исхода среды не пришлось.
На утро есть 35 сердечек.
Значит, курсу быть.

В понедельник (23.09) опубликую подробности и правила.
Не теряйтесь.

Приехал-таки мой диплом.
Теперь официально: технический писатель системный аналитик.

Привет, сегодня понедельник, 23.09, а значит, пора начинать наш мини-курс по проектированию API.

Итак, тренироваться будем на кошках техписах.
В рамках курса мы спроектируем и задокументируем API (REST like, не побоюсь этого слова) в соответствии с ТЗ:

Цель: Разработать API для управления базой данных о технических писателях и их навыках.

Сущности, которыми будет оперировать API:
Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скилл), контактные данные.
Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.

Действия, которые будут реализованы в API:
- Получение списка технических писателей.
- Получение списка скиллов.
- Получение информации о техническом писателе по идентификатору.
- Получение информации о навыке.
- Добавление нового технического писателя.
- Редактирование сведений о техническом писателе.
- Удаление технического писателя.
- Добавление нового навыка.
- Редактирование навыка.
- Удаление навыка.

А теперь правила, ограничения, условия:

1. Не будем запихивать в сущности кучу полей. Наша цель все-таки — научиться документировать.
2. Не будем пытаться соблюсти все паттерны проектирования API и следовать best practices. Наша цель — см. П1.
3. Не будем описывать схему и принципы авторизации. Про цель вы в курсе :), да?
4. Не будем останавливаться на каких-то базовых вещах типа установки git на компьютер, настройки рабочего окружения и, глубокой теории по технологиям и инструментам. Но если будут возникать вопросы, будем стараться решать их вместе.

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

Посты из курса буду помечать хэштегом #apidocs.

Вопросы, жалобы, предложения?

Следующий пост будет в четверг, 26.09: займемся описанием и проектированием сущностей API.

До встречи.