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

Увидел в лифте такие вот правила пользования.
И они мне сломали мозг. Попросил жену и детей посмотреть на это и сказать, что здесь не так.
И все трое, включая 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.

До встречи.

#apidocs
Привет. Продолжаем курс по документированию API.

Сегодня посмотрим, как описываются методы API в формате Open API. Т.е. после занятия у нас уже будет документация, которую можно показывать разработчикам.

Для описания API будем использовать спецификацию OpenAPI v3.0.0. Почему не более v3.1.0 свежую от 2021 года? v3.0.0 хоть и была опубликована в 2017 году, ее и сейчас «по инерции» используют многие. К тому же и некоторые привычные всем инструменты (например, Swagger Editor) «ругаются» на v3.1.0.
В одном из следующих уроков обязательно рассмотрим разницу между этими версиями спецификации.

Описывать API можно в формате YAML или JSON: как вам удобно. В курсе будем использовать YAML.

Итак, писать спецификацию на API в формате OpenAPI v3.0.0 можно с помощью разных инструментов. Выбирайте удобный:

- https://editor.swagger.io/ — онлайн-редактор из состава экосистемы инструментов «Swagger».
- https://app.swaggerhub.com/ — тоже онлайн-редактор. Нужна регистрация. На бесплатном аккаунте можно создавать и публиковать до трех описаний API.
- Плагин OpenAPI (Swagger) Editor для VS Code — редактор со Swagger UI прямо в IDE.

Давайте рассмотрим создание описания API в формате OpenAPI на примере метода для получения информации об одном техническом писателе.

Ресурс «Технический писатель» мы спроектировали на предыдущем уроке. Теперь давайте опишем в формате OpenAPI его и метод для получения одного техписа (одного ресурса).

Спецификация в формате OpenAPI — это один большой объект (он же — схема), который состоит из полей и объектов поменьше (они, в свою очередь тоже состоят из объектов).
Состав «корневого» объекта описан в спецификации (https://spec.openapis.org/oas/v3.0.0#fixed-fields). Видно, что часть объектов здесь обязательная, а часть — нет.

Мы в курсе будем использовать следующие из них:
- оpenapi — обязательное поле. Здесь указывается, версия спецификации OpenAPI, в которой описывается API.
- info — обязательный объект. Здесь указывается информация непосредственно о нашем API (описание, версия и т.д.)
- tags — необязательный. Используется для группировки методов API. Это нужно, например, для того, чтобы разработчики и пользователи API могли лучше ориентироваться в документации.
- paths — обязательный объект. Здесь описываются конечные точки (методы) API.
- components — необязательный объект. Здесь описываются повторно используемые компоненты, которые могут быть использованы в различных частях документации.

Теперь рассмотрим это на конкретном примере.
По ссылке размещен фрагмент спецификации на наш API, в которой описан метод для получения информации об одном техническом писателе.
Вы можете скопировать ее в любой из указанных выше инструментов и посмотреть, как это все работает.
Кратко поясняю, что здесь происходит:
- Строка 1. В объекте оpenapi указано, что документация на API подготовлена в формате OpenAPI v3.0.0.
- Строки со 2 по 12. В объекте info указана основная информация про API: краткой и развернутое описание и версия. Здесь можно использовать, например, html-теги, чтобы в Swagger UI или на статическом сайте это выглядело красиво и удобочитаемо.
- Строки с 13 по 15. В объекте tags указан (это) пока, один тег для группировки методов в документации.
- Строка 16. Отсюда начинается описание методов (конечных точек).
- Строки с 17 по 43. Здесь описан метод для получения информации об одном техническом писателе /techwriters/{techwriterId}.
- Строка 44. Отсюда начинается объект components.
- Строки с 46 по 94 — здесь описан ресурс (объект) Techwriter, который возвращается в ответе метода для получения информации об одном техническом писателе /techwriters/{techwriterId} (на этот ресурс есть ссылка из описания метода в строке 39).
- На закомментированные строки с 95 по 98 внимания не обращайте. Этот объект автоматически сгенерирован сервисом https://app.swaggerhub.com/.

(продолжение предыдущего поста #apidocs)

Посмотреть, что получилось, можно здесь.

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

Что дальше? В следующих уроках опишем остальные методы, рассмотрим разницу между описаниями API в формате OpenAPI v3.0.0 и OpenAPI v3.1.0, а затем будем генерировать и кастомизировать статический сайт-справочник (еще один вид документации на API).

Описание этапа получилось краткое. Если у вас есть вопросы, готов ответить. Пишите в комментариях к посту или в личку.

В комментариях вы просили отдельный пост про обучение в «Нетологии»?
Держите отдельную статью.

#apidocs

Наступил вечер пятницы, а наш API обзавелся новыми методами для получения нужной информации.
Актуальные для данного этапа спецификации — на Gitlab и SwaggerHub.

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

#apidocs

Привет.
Продолжаем курс по документированию API.

Первое

После прошлого поста у самых внимательных появились вопросы (спасибо, за то, что наблюдаете и поправляете).
В частности, при проектировании ресурса «Технический писатель» мы указали:

|Название поля|Имя поля в API|Тип данных|
|-------------|--------------|----------|
|Имя          |firstName     |string    |

А при подготовке спецификации я вместо firstName написал name. Ошибку пофиксил, спасибо за замечание (тык, тык).

Второе

На этапе проектирования мы предполагали, что будем оперировать двумя основными ресурсами: «Технический писатель» и «Навык». Но в процессе пришло понимание, что лучше будет ввести еще один (составной) ресурс «Навык технического писателя».
Почему так? Если оставить все как есть, то при добавлении каждого нового техписа для него нужно будет добавлять один или несколько навыков. Но ведь навыки у большинства техписов, как правило типовые (за исключением каких-то специфичных), например «Документирование API», «MkDocs», «Документирование кода» и т.д. Если для каждого техписа отдельно хранить полное описание набора навыков, у нас получится много дублей, что не есть хорошо.

Поэтому было принято решение:

1️⃣ Изменить ресурс «Навык». В частности, убираем из него поля «Подтверждающий документ» и «Ссылки на примеры».

|Название поля  |Имя поля в API  |Тип данных|
|---------------|----------------|----------|
|Идентификатор  |id              |integer   |
|Название навыка|skillName       |string    |
|Описание навыка|skillDescription|string    |
|Алиас          |alias           |string    |

Теперь у нас будут какие-то типовые навыки, общие для всех техписов. А для каждого конкретного специалиста они будут обогащаться данными.

2️⃣ Ввести составной ресурс «Навык технического писателя».
Он будет строиться из типового «Навыка» и дополняться полями, индивидуальными для каждого техписа. И выглядеть это может так:

|Название поля            |Имя поля в API.   |Тип данных    |
|-------------------------|------------------|--------------|
|Идентификатор техписателя|techwriterId      |integer       |
|Общая информация о навыке|skillCommonInfo   |object (навык)|
|Подтверждающий документ  |confirmingDocument|string        |
|Ссылки на примеры        |linksExamples     |array(string) |

Собственно, это сейчас и отражено в наших спецификациях.

Что дальше? Дальше добавим методы для добавления и изменения данных и перейдем к документированию API. Оставайтесь на связи.

Что-то давно стихов IT-шных у нас не было.
Придумалось вот за рулем:

На проде аффектится импорт.
На «тесте» регресс не прошел.
Я «фича» ребейзнул — конфликты.
QA новый баг вдруг нашел.

Тимлид мой МР не аппрувит.
Тех. дир вдруг позвал уан ту уан.
Стажер, блин, скиллы не импрувит.
На кой мне такой падаван?

#apidocs

Привет.
Суббота, все отдыхают, а наша спецификация API пополнилась новыми методами для добавления, изменения и удаления данных.

По сути, у нас все уже готово.

В начале курса мы условились, что в проектируемом API будут реализованы действия:
1️⃣ Получение списка технических писателей (метод GET /techwriters).
2️⃣ Получение списка скиллов (метод GET /skills).
3️⃣ Получение информации о техническом писателе по идентификатору (метод GET /techwriters/{techwriterId}).
4️⃣ Получение информации о навыке (метод GET /skills/{skillId}).
5️⃣ Добавление нового технического писателя (метод POST /techwriters/).
6️⃣ Редактирование сведений о техническом писателе (метод PATCH /techwriters/{techwriterId}).
7️⃣ Удаление технического писателя (метод DELETE /techwriters/{techwriterId}).
8️⃣ Добавление нового навыка (метод POST /skills).
9️⃣ Редактирование навыка (метод PATCH /skills/{skillId}).
🔟 Удаление навыка (метод DELETE /skills/{skillId}).

Итоговую спецификацию смотрите на SwaggerHub или в GitLab.

Пояснения и ответы на вопросы (если они будут) — на следующей неделе.

И еще. Делюсь полезным инструментом, который поможет вам визуализировать спецификацию в формате YAML, чтобы было удобнее смотреть «что откуда растет». Это — PlantUML. Нужно просто обернуть спецификацию в теги

@startyaml  @endyaml 

и она отрисуется в виде картинки. Но есть нюанс: некоторые плагины PlantUML не понимают символ «|» в YAML (используется для многострочных блоков текста). Поэтому спецификацию нужно предварительно подготовить: убрать «|», блоки сделать в одну строку и убрать из них служебные символы (т.к. в этом случае уже будет «ругаться» YAML). Посмотреть, как это выглядит, можно, открыв в вашей IDE этот файл. Но у вас должно быть установлено расширение для работы с PlantUML (я использую VSCode и расширение PlantUML для него). Возможно, с вашим плагином (если будете использовать что-то другое) такого не случится, кто знает :).

Теперь, у нас уже есть одна из форм документации API — спецификация в формате OpenAPI.

Что дальше? А дальше мы будем генерить из нее статический сайт-справочник (не без docs as code, конечно же).

Будьте на связи.