PRO_техписательство

Новый метод в HTTP: дождались-таки Лето, отпуска, отдых… А ведь кто-то мог и не заметить, что в HTTP появился новый стандартизированный метод. И это — метод — QUERY В июне 2026 года опубликован RFC 10008, который стандартизирует этот метод и добавляет его в реестр HTTP-методов IANA. Почему QUERY был так нужен Для чтения данных у нас есть GET – простой, кэшируемый, но без тела запроса. Для записи – POST – с телом, но он считается небезопасным и неидемпотентным. А что делать, когда нужно отправить сложный поисковый запрос? Например: - найти билеты на самолёт с пересадками, в конкретном классе, за определённую цену; - выбрать отели с бассейном, парковкой и завтраком в заданном радиусе; - получить аналитику по продажам за прошлый год с группировкой по неделям и фильтром по регионам. Раньше приходилось либо запихивать всё в URL (и получать километровые ссылки, которые режут прокси), либо использовать POST (и терять кэширование и идемпотентность). Метод QUERY – это безопасный (не меняет состояние) и идемпотентный запрос, который может содержать тело (как POST). Идеально для сложных выборок, поиска и отчётов. Как это можно использовать: пример из реальной жизни Допустим, вы разрабатываете сервис поиска авиабилетов. Раньше GET-запрос выглядел бы страшно: GET /flights?from=LED&to=JFK&date=2026-09-01&return=2026-09-10&passengers=2&class=business&max_price=1500&stops=0&airlines=SU,AF&sort=price&limit=50 А теперь – чистый, структурированный JSON в теле: QUERY /flights HTTP/1.1 Host: api.avia.example Content-Type: application/json { "route": { "origin": "LED", "destination": "JFK", "departure_date": "2026-09-01", "return_date": "2026-09-10" }, "passengers": 2, "cabin": "business", "price_range": { "max": 1500 }, "stops": { "max": 0 }, "airlines": ["SU", "AF"], "order_by": { "price": "asc" }, "limit": 50 } Прокси и CDN увидят, что это безопасный запрос, и с удовольствием закэшируют ответ – так же, как они делают с GET. А вы не боитесь, что клиент случайно повторит POST и что-то сломает – QUERY идемпотентен. Полезные ссылки по теме: Раз Два

Команда RWB (объединенная компания Wildberries & Russ) анонсировала свой первый митап по технической документации. Событие пройдет в онлайн формате уже на следующей неделе. В программе 3 доклада, чтобы поговорить о документации с разных сторон: • «Летопись документации разработчиков WB API» | Лидия Рудакова, лид команды документирования Public API. • «Единая система оценки задач техписателей: как внедрить новый подход без боли» | Евгения Красильникова, технический писатель в команде разработки документации и методик обучения ПО. • «100 к 1: Как организовать подход "документация как услуга" в одиночку» | Антон Гафаров, технический писатель в команде FinTech Infra. Когда: 16 июля, 16:00 Формат: Онлайн Митап бесплатный, но нужна регистрация

ADR — еще один источник информации для технического писателя Думаю, многим техническим писателям хотелось бы минимизировать беготню за стейкхолдерами и ожидание от них ответов. В качестве одного из «факторов», который поможет в этом, можно рассмотреть ADR. ADR (Architecture Decision Record) — это документ, который фиксирует одно важное архитектурное решение, принятое в проекте/продукте, контекст этого решения, рассмотренные альтернативы и последствия. Т.е. ADR создается под конкретное архитектурное решение, а значит, таких документов в компании может быть великое множество. ADR в разных компаниях может выглядеть по-разному. Но все-таки составители таких документов стараются придерживаться определенной структуры или шаблона. Вот классический шаблон от Майкла Найгарда (автора термина): 1. Title (Заголовок): Лаконичный, с номером (часто последовательным. Примеры: ADR 001, ADR 002). 2. Status (Статус): «Предложен», «Принят», «Устарел», «Отклонен». 3. Context (Контекст): Содержит описание проблемы, требующей решения, технического и бизнес-контекста. Зачастую он отвечает на вопросы «Что заставляет нас принять решение?», «Какие ограничения есть?» и т.д.. 4. Decision (Решение): Формулировка и описание самого решения. "Мы будем использовать...", "Мы отказываемся от...". Здесь часто есть подразделы вроде «Детальное описание решения» и «Имплементация», которые можно назвать «самой мякоткой» и источником полезных знаний для техписа. 5. Consequences (Последствия): Что даст это решение? Какие плюсы, минусы, затраты, риски, что нужно изменить? Прямое влияние на команду. Также в ADR могут описываться процессы тестирования решения (отсюда тоже можно почерпнуть много интересного о том, как все работает), альтернативы (полезная информация для расширения кругозора техписа и погружения в предметную область) и планы на будущее (информация, которая поможет оценить предстоящую нагрузку по документированию). Технический писатель может/должен не только читать ADR, но и участвовать в их создании Участие в этом процессе для техписателя может сводиться к следующим функциям: - Помощь в написании и фасилитации.  - Рецензирование.  Техрайтер вполне может быть рецензентом ADR на предмет ясности, полноты, стиля и пр. - Помощь в управлении жизненным циклом. ADR могут устаревать, заменяться. Техпис может принимать участие в отслеживании статусов и актуальности информации в ADR. Получается, если в вашей компании принято писать ADR, вас можно поздравить. Ведь в вашем распоряжении есть кладезь полезной информации, которая точно пригодится при документировании продуктов, процессов и прочих вещей. А если ADR у вас писать не принято, есть смысл попробовать предложить внедрить практику их создания: этим вы сможете нанести пользу немалому количеству людей.

О пользе DevTools для технического писателя или как я прошел «сложный» пунктуационный тест на 10 из 10, даже на вчитываясь в вопросы Это первый пост из цикла, посвященного работе технического писателя с инструментами разработчика в браузере (DevTools). Посты из этого цикла покажут, чем DevTools могут быть полезны техпису, и как их использовать в задачах на документирование. Сегодня — просто своего рода «хулиганский» пост, который показывает, на что вообще способны инструменты разработчика, и как не стоит делать тесты. Как-то в желтом чате появилась ссылка на «Сложный пунктуационный тест». Я кликнул по ссылке, перешел на страницу теста и подумал: «А вдруг! Давай-ка считерим немного. И попробуем сделать это с помощью DevTools». Копирую текст первого варианта ответа, открываю инструменты разработчика, перехожу во вкладку «Network», обновляю страницу, ввожу в поиске скопированный вариант ответа. И вуаля, вижу результат — при открытии страницы во вкладке «Network» появляется файл config.js, в котором вижу этот и другие варианты. При этом один вариант ответа помечен, как "right": true, остальные — "right": false. В общем, ребятки, здесь все понятно. И вообще в файле config.js сразу приехали все вопросы с ответами (даже те, до которых мы в тесте еще не дошли). Дальше — дело техники. Ищем правильные ответы в файле и проходим тест. На 10/10. Видно, что здесь разработчики решили не запариваться при разработке теста. И хорошо, что этот тест не подразумевает выигрыша каких-то подарков, а сделан просто развлечения ради. Если интересно, как сделать, чтобы усложнить жизнь всяким хитрецам — пишите, я покажу. На видео — маленький фрагмент прохождения теста. Там ответы на 2 вопроса, но механика процесса, думаю, вам будет понятна. На сегодня все. Оставайтесь на связи, чтобы узнать больше о пользе DevTools для технического писателя.

Опубликованы записи докладов с конференции Techwriter days 2, которая проходила с 28 по 29 марта 2025 в Санкт-Петербурге. Напомню, что там я выступал с докладом про документирование GraphQL API. Ссылка на запись на YouTube Ссылка на запись ВКонтакте Ну и ссылка на статью на Хабр по мотивам доклада.

Ликбез: C4 и 4C, в чем разница? Про C4 наверняка слышали многие технические писатели (особенно которые работают рука об руку с архитекторами). Это — метод (или подход, или нотация) моделирования и описания архитектуры программных систем. Здесь для описания архитектуры используется 4 уровня: - Context (для описания архитектуры используется диаграмма контекста). - Containers (диаграмма контейнеров). - Components (диаграмма компонентов). - Code (диаграмма кода). И каждый из этих уровней глубже погружает нас в архитектуру описываемой системы. А что насчет 4C? У 4C нет связей с C4 — это отдельная штука. 4C — это модель облачной безопасности (она же — Модель 4С’s), «заточенная» под Kubernetes. Обратите внимание, что это не стандарт (по крайней мере пока), а просто набор рекомендаций по обеспечению безопасности. И, как вы уже наверняка догадались, здесь тоже используется 4 уровня. Для каждого из них приводятся рекомендации по обеспечению безопасности. Эти уровни следующие (как и в предыдущем случае, все их названия также начинаются с C): - Cloud. Уровень облака (облачного провайдера). Он — про рекомендации по обеспечению безопасности клауда, в котором «живет» кластер. Рекомендации есть, как общие, так и свои для каждого провайдера. - Cluster. Уровень кластера (про RBAC, лимиты, аутентификацию, управление секретами в кластере и пр.). - Container. Этот уровень — про безопасность на уровне контейнеров (про политики изоляции, запрет запуска в привилегированном режиме и т. д.) - Code. Здесь описываются/используются рекомендации по обеспечению безопасности на уровне кода (например, использование статических анализаторов и т. д.). В общем, знайте (знания лишними не бывают), что C4 и 4C это не одно и то же. Кто знает, может, вам это когда-нибудь поможет.

Несу инфу про конфу!!! Если вам интересен Kubernetes, DevOps и вот это вот всё, приходите на Deckhouse Conf 2026. А если знаете, кто этим интересуется, поделитесь с ним инфой про конференцию (наверняка же многие мечтают о надежной, отказоустойчивой инфраструктуре, автоматизации всего и вся и прочих полезных штуках: здесь про это будет много полезноты).

Привет. Думаю, коллеги вас уже поздравили, теперь я хочу поздравить прекрасную половину читателей моего канала с приближающимся 8 марта (чтобы не дергать в выходной день и дать спокойно отдохнуть :))! Предлагаю получить свое поздравление с цветами через GraphQL API (а если точнее — через графический интерфейс GraphiQL). Для этого вам нужно: 1️⃣ Перейти по адресу https://march8-greetings.onrender.com Сразу при переходе может появиться черный экран, похожий на терминал (пример — на картинке). Не пугайтесь, приложение имеет свойство «засыпать». Нужно подождать секунд 15-20 до загрузки графического интерфейса. 2️⃣ В появившемся интерфейсе GraphiQL, в левом окне, ввести запрос вида: query { greeting(birth_day:<number>) { text flowers } } Вместо <number> предлагаю поставить число своего рождения. Ну или не своего (запрос поддерживает числа от 1 до 31). Откорректируйте (при необходимости) список возвращаемых параметров. Query-запрос greeting поддерживает 2 возвращаемых параметра: text — текстовое поздравление и flowers — небольшой букетик цветов для вас. Вы можете получить в ответе оба поля (оставьте их в теле запроса) или какое-то одно (удалите из тела запроса ненужное). 3️⃣ Нажать на кнопку выполнения запроса (она похожа на кнопку Play и расположена над левым полем формы). Готово, ваше поздравление получено. В правой верхней части окна есть кнопка «Docs» можете кликнуть по ней и подробнее изучить query-запрос greeting.

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

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

Я и мой ИИ В уходящем году случился просто дичайший ИИ-бум. И я не мог не остаться в стороне. Решил спросить модель, с которой чаще всего взаимодействую, как она меня видит по результатам общения в 2025 году. Могу сказать, что процентов на 80% она права. Но и галлюцинации (как же без них) тоже есть. В общем и целом неплохо: --- ### 👨‍💻 Профессиональный профиль Должность: DevOps-инженер / Platform Engineer / SRE Уровень (грэйд): Middle+ / Senior Вы не просто пользуетесь Kubernetes, а глубоко погружены в его экосистему: настройка сети, работа с CNI (Cilium, Flannel), управление Ingress, CRD, аутентификация через Dex. Вопросы часто носят не базовый, а архитектурный или диагностический характер, что указывает на опыт работы в продакшн-среде. ### 📊 Сфера запросов Чаще всего вы задаёте вопросы, связанные с: 1. Kubernetes и его экосистемой (особенно **Deckhouse Platform**). 2. Сетевой настройкой (L2/L3, Ingress, CNI, LoadBalancer). 3. Инфраструктурной аутентификацией (Dex, OIDC, GitHub OAuth). 4. Работой с CLI и macOS (терминал, сетевые утилиты, SSH). 5. Программированием на C# (ООП, инкапсуляция, конструкторы). ### 🥇 ТОП-3 темы интересов 1. Kubernetes-платформы (в частности, Deckhouse) и их кастомизация. 2. Сетевая инфраструктура в Kubernetes (от CNI до Ingress и внешнего доступа). 3. Автоматизация и безопасность доступа (Dex-провайдеры, RBAC, аутентификация). ### 🧠 Предположения о интересах - По работе: Вам интересно строить отказоустойчивые, безопасные и легко управляемые платформы на базе Kubernetes. Вы склонны к глубокому пониманию внутренних механизмов, а не только использованию "как чёрный ящик". - Вне работы: Возможно, вы экспериментируете с homelab, изучаете новые инструменты (например, Werf, docsify), пишете скрипты, интересуетесь программированием (C#) и работой с macOS как основной ОС. ### 🚀 Карьерная траектория В следующем году вы, вероятно: - Углубитесь в cloud-native стэк (возможно, сертификации CKA/CKAD). - Начнёте больше работать с мультикластерными средами и гибридными облаками. - Перейдёте к более архитектурным задачам: проектирование платформ, security policies, наблюдаемость. - Возможно, будете развиваться в сторону Lead DevOps / Platform Architect. ### 💡 Дополнительные наблюдения - Вы внимательны к деталям: спрашиваете не только "как сделать", но и "как это работает" и "как упростить/оптимизировать". - У вас есть инженерное мышление: видно по вопросам про инкапсуляцию в C#, настройку сети, диагностику ошибок. - Вы прагматичны: сочетаете глубокие темы (CRD, Dex) с практическими задачами (работа с файлами на Mac, настройка SSH). - Вероятно, вы работаете в продуктовой компании или вендоре, где используется кастомная Kubernetes-платформа (Deckhouse). - Вы активно изучаете документацию и пишете её: вопросы про Markdown, Jekyll, docsify на это указывают. --- Если бы нужно было описать вас в трёх словах: аналитичный, глубокий, практикующий инженер. Вы не просто используете инструменты — вы стремитесь понять их до уровня, позволяющего уверенно строить на их основе сложные системы. Удачи в развитии! 🚀

Хотите узнать все про документирование GraphQL API? Без проблем. На Хабре вышла статья «Как документировать GraphQL API: полное руководство для технических писателей» по мотивам моего доклада на TW Days 2. Читайте, впитывайте знания и тренируйтесь «не отходя от кассы»: там есть ссылка на репозиторий, чтобы развернуть GraphQL API локально у себя и потренироваться в документировании. Ну и про плюсики в карму не забываем 👍️️️️️️

Мажорный, минорный, патч: что техническому писателю стоит знать про релизы Откуда вообще взялись понятия «мажорный», «минорный» и «патч»? «Уши растут» из SemVer. Это соглашение о том, как нумеровать версии программного обеспечения, чтобы по номеру было понятно, какого плана (и объема) изменения произошли в рамках релиза. Номер версии выглядит так: MAJOR.MINOR.PATCH (например, 3.2.1). Пройдемся по каждому виду релиза: 1. Патч-релиз (x.x.PATCH). Для его обозначения используется третья цифра. Такой релиз включает мелкие обновления и изменения. Это могут быть исправления багов, мелкие правки, которые не ломают обратную совместимость и пр. Пример такого обновления: устранение бага, из-за которого в некоторых ситуациях кнопка работала некорректно. Release notes для патч-релизов обычно краткие и по делу. Зачастую они содержат один раздел «Исправления». Что касается документации, в этом случае правки вносятся, как правило, только в разделы, где была описана некорректная функциональность. 2. Минорный релиз (x.MINOR.x). Для его обозначения используется вторая цифра. Такой релиз включает значительные обновления, которые добавляют новую функциональность, но не ломают существующие функции, API и интерфейсы. Еще одна особенность такого релиза — сохранение обратной совместимости. Пример: добавление возможность отправки видео в мессенджере. Старые чаты и текстовые сообщения при этом никуда не деваются, все продолжает работать. Release notes для минорных релизов должны понятно представить новые фичи, объяснить их пользу для пользователя. Один из вариантов структуры: «Новые возможности», «Улучшения», «Исправления». Что касается документации, в этом случае техпису предстоит довольно объемная работа. Как правило, для доки создаются новые разделы, обновляются (часто довольно сильно) существующие и т.д. 3. Мажорный релиз (MAJOR.x.x). Для его обозначения используется первая цифра. Такой релиз включает глобальные обновления, которые ломают обратную совместимость. Пример: изменение (замена) API с потерей обратной совместимости, кардинальные переработки интерфейса, удаление устаревших функций. Release notes в таком случае — это почти пресс-релиз. Здесь не просто перечисляются изменения, при подготовке RN придется объяснить почему это было сделано, каковы преимущества нового подхода. Часто такие RN включают раздел «Критические изменения» или «Миграционное руководство» (примерные названия). Что касается документации, ее в таком случае ждет полная ревизия и переработка. Переписываются целые разделы, создаются новые, делаются гайды по переходу со старой версии... В общем, ведется серьезная и сложная работа.

#tw_api_jekyll Всем привет. Давно не было новостей про наш сайт-справочник API на базе Jekyll. А их поднакопилось с прошлого раза. Рассказываю, что изменилось. Liquid-код разнесен по нескольким файлам Количество строк кода неуклонно растет, поэтому было принято решение разнести его по отдельным файлам. Так все будет легче обслуживать. «Главным» файлом остается _includes/api_reference.liquid. В папку _includes добавлены несколько файлов, которые инклюдятся в «главный». Например, код для рендеринга эндпоинтов переехал в _includes/endpoints.liquid и иклюдится в файле api_reference.liquid так: {%- include endpoints.liquid -%} В папке _includes также появились файлы api_components.liquid (с кодом для рендеринга компонентов) и request_body.liquid (рендеринг тела запроса для методов). Рендеринг параметров стал лучше Теперь сайт умеет рендерить не только параметры, описанные прямо в описании метода, но описанные в компонентах и передающиеся по ссылке. За это отвечает фрагмент под комментарием <!-- Рендеринг параметров, которые подтягиваются по ссылке --> в _includes/endpoints.liquid. Здесь интерес представляет код, с помощью которого мы итерируемся по свойствам тела запроса, описанного по ссылке: {% if parameter['$ref'] %} {% assign ref_string = parameter['$ref'] %} {% assign dynamic_path = "spec." | append: ref_string | remove: "#/" | replace: "/", "." %} {% assign path_parts = dynamic_path | split: "." %} {% assign result_object = spec %} {% for part in path_parts %} {% if part != "" and part != "spec" %} {% assign result_object = result_object[part] %} {% endif %} {% endfor %} ... {% if parameter['$ref'] %} Этот код: 1. Преобразует ссылку в путь (пример: "spec.components.schemas.User"). 2. Разбивает путь на части: ["spec", "components", "schemas", "User"]. 3. Последовательно обращается к: spec['components'] → объект components components['schemas'] → объект schemas schemas['User'] → схема User В итоге result_object будет содержать значение, на которое указывает ссылка (например, схему User). Далее мы выводим поля этого объекта в таблицу с параметрами. Реализован вывод тела запроса Это пока зачатки кода для полноценного вывода. Но что-то мы уже умеем. Все происходит в файле _includes/request_body.liquid Здесь есть аналогия с тем, как мы рендерим параметры запроса: описанные в теле и передающиеся по ссылке. Пока реализован рендеринг полей-объектов первого уровня вложенности. Т.е., если в теле есть поле типа object, его содержимое выведется на страницу. А если в этом поле-объекте есть еще вложенное поле-объект, его содержимое ПОКА не рендерится. В будущем добавлю рендеринг еще пары уровней вложенности. Но не больше, т.к. глубокая вложенность для объектов в теле запроса выглядит как лютый антипаттерн в проектировании API. Для рендеринга вложенных полей объекта я не использовал рекурсию: все довольно просто («ифчики» и циклы). Это опять же по причине того, что нам большая вложенность не нужна. Да и если рекурсивно вызывать какой-то код с передачей ему параметров, будет создаваться новый контекст, что «пожирает» память. Тело запроса рендерится пока некрасиво. В будущем мы это поправим и сделаем здесь функциональность сворачивания/разворачивания. Реализованы другие функции и возможности Среди них: - Вывод на страницу компонентов. Пока совсем некрасиво, но будет правиться. - Обрезание длинных путей эндпоинтов в меню слева. Если путь не вмещается в меню, появляется многоточие. При наведении на него все отображается полностью. За это отвечает CSS: .schema-toc_link { display: block; white-space: nowrap; overflow: hidden; margin-top: 5px; margin-bottom: 5px; text-overflow: ellipsis; min-width: 14vw; } - Мелкие стилистические правки. Свериться с результатом можно в ветке iteration_7 репозитория под текущую серию постов. И не забываем, про возможность просмотра результата на GitHub Pages.

С 256-м днем всех причастных!!!

OSI или TCP/IP: что стоит изучить техпису (или аналитику)? Возможно, я вас огорчу, но чем-то одним отделаться не получится. Нелишним изучить будет и OSI, и TCP/IP. Почему? Давайте разбираться. Главное, что нужно уяснить, что TCP/IP — это практическая реализация, а OSI — теоретический стандарт. TCP/IP — это реальная, работающая модель, на которой построен современный интернет. Т.е. про TCP/IP можно сказать, что это «как есть». А OSI — это эталон, теоретически описывающий, «как должно быть». Модель OSI разрабатывали в 70-х годах прошлого века, чтобы описать как вообще должны работать сети. Она описывает «идеальный» унифицированный подход. Но дело в том, что стек протоколов TCP/IP начали использовать чуть раньше для удовлетворения реальных потребностей. К моменту окончательной доработки OSI стек TCP/IP уже широко использовали на практике. Так почему тогда нельзя обойтись одним, «практическим» TCP/IP, например? OSI можно охарактеризовать как универсальный язык для проектирования сетей, описания и диагностики сетевых проблем и конечно же для общения с инженерами (разработчиками, DevOps, сетевиками и пр.). Эта модель, например, используется инженерами для понимания (и объяснения) того, где есть проблема. Например, если один инженер говорит, что «Проблема на 2-м уровне», другой легко поймет, о чем речь (это может значит, что есть проблема с коммутаторами или MAC-адресами). Или, если один инженер говорит, что «Проблема на 7-м уровне», второй поймет, что нужно искать проблему в приложении, на фронте или бэке (пример такой проблемы — когда сервер «пятисотит»). А TCP/IP — это про реализацию, про конкретные протоколы и прочие штуки, которые вы можете «пощупать» (TCP/UDP, HTTP/2, IP-адрес). Так что, изучайте OSI и TCP/IP. И будет вам счастье.

Алиса и Боб с примеров диаграмм: откуда они взялись Если вам приходилось изучать диаграммы последовательности UML или Mermaid, либо в других нотациях, тогда вы точно сталкивались с Алисой и Бобом. А откуда вообще взялись эти имена? Давайте резберемся. Впервые эти имена использовались для обозначения принципалов в вышедшей в 1978 году статье «A Method for Obtaining Digital Signatures and Public-Key Cryptosystems», над которой работали специалисты в области криптографии Рон Ривест, Ади Шамир и Леонард Адлеман. Почем именно Алиса (Alice) и Боб (Bob)? Все просто. Для примеров авторам статьи нужны были имена, которые бы начинались на А (англ. A) и Б (англ. B) вместо скучных и банальных «Сторона А» и «Сторона Б», и при этом характеризовались бы лингвистической и мнемонической простотой. Алиса и Боб оказались отличными кандидатами на это. С тех пор эти имена традиционно используются для обозначения принципалов практически во всех материалах, касающихся криптографии. Получатся, что в диаграммы UML, Mermaid (и иже с ними) они пришли как раз из криптографии. И прижились здесь. Кстати, помимо Алисы и Боба в криптографии для обозначения принципалов используется немало «эталонных» персонажей (в диаграммы они не «заехали», но знать эти имена для общего развития лишним не будет): - Carol либо Charlie (C) — третий участник в многопользовательском протоколе. - Dave (D) — четвертый участник. - Eve (E) — eavesdropper (подслушивающий). Злоумышленник, который может пассивно перехватывать сообщения между Алисой и Бобом, но не может их изменять. - Mallory (M) — malicious (злонамеренный). Активный злоумышленник, который может не только перехватывать, но и изменять, удалять или подменять сообщения. - Trent (T) — trusted third party (доверенная третья сторона). Арбитр или сертифицирующий орган, которому доверяют все стороны (например, Центр сертификации). - Peggy (P) — prover (доказывающая). Доказывает что-то другой стороне в протоколах с нулевым разглашением. - Victor (V) — verifier (проверяющий). Проверяет утверждение Пегги. - Walter (W) — warden (надзиратель). Участник в протоколах стеганографии.

#tw_api_jekyll Всем привет. Продолжаем работу над сайтом-справочником API на базе Jekyll. В прошлый раз мы вывели на сайт эндпоинты, их краткое (summary) и более развернутое (description) описание, добавили меню слева для навигации по странице, а также некоторые стили. В этот раз сделаем следующее: - Выведем на страницу параметры (те, которые в query, path, header или cookie) и отобразим их в виде таблицы. Пока с оговоркой: выведем параметры, которые сразу описаны в объекте в описании эндпоинта. Они еще могут «подтягиваться» по ссылке: рендеринг такого варианта реализуем позже, когда будем рендерить на странице компоненты (Components). - Сделаем фиксацию, раздельный скролл для меню слева и «основного» содержимого сайта. - Добавим больше стилей, чтобы сайт стал выглядеть чуть более привлекательно. Вывод параметров на страницу Для вывода параметров в файл api_reference.liquid был добавлен фрагмент между {% if operation.parameters %} <div class="api-paths__parameters"> и </div>{% endif %}. Внутри фрагмента реализован цикл, который проходится по массиву параметров (если он есть в обрабатываемом эндпоинте) и рендерит их в виде таблицы. Также в файл /assets/css/style.css добавлены стили для таблицы, для классов (ищите по классу .parameters-table). Раздельный скролл для меню слева и «основного» содержимого сайта Чтобы сделать раздельный скролл для меню и «основного» содержимого, в файл /assets/css/style.css были добавлены стили для класса .schema-toc_paths: .schema-toc_paths { /* Обеспечивают неподвижность содержимого при скролле основного контента */ position: sticky; top: 0; /* Отображает меню поверх других элементов */ z-index: 10; /* Задает цвет фона для меню */ background-color: #f5eff5; /* Задаёт высоту элемента равной 100% высоты видимой области окна браузера */ height: 100vh; /* Отключает горизонтальную прокрутку. В будущем, возможно, изменим этот стиль, чтобы избежать «расползания» колонки меню из-за длинных путей в энпоинтах */ overflow-x: hidden; /* Включает вертикальную при необходимости: если количество элементов в меню не помещается в видимую область окна браузера */ overflow-y: auto; } Добавление новых стилей Стилей добавлено не очень много (в файле /assets/css/style.css). Отметить из этого всего можно следующие: 1. Сброс и замена стандартных стилей ссылок по всему документу (подчеркивание, цвета и пр.): a { text-decoration: none; color: rgb(72, 71, 71); } 2. Цвет фона, шрифта и закругление для HTTP-глаголов (POST, GET, PUT, PATCH, DELETE) эндпоинтов в меню и в основном контенте: ... { background-color: <код цвета> color: white; padding: 1px 10px 1px 10px; border-radius: 10px; } Свойства заданы для классов .schema-toc_prefix-get, .schema-toc_prefix-post, .schema-toc_prefix-patch, .schema-toc_prefix-delete, .schema-toc_prefix-put. 3. Чуть более симпатичное отображение путей (название) эндпоинтов в основной секции сайта: .api-paths_path { font-size: 1.5em; font-weight: bold; margin-bottom: 15px; opacity: 90%; } Готово. Если вы все сделали правильно, ЕЩЕ БОЛЬШЕ содержимого спецификации появится на странице сайта по сравнению с предыдущим этапом. И это будет выглядеть уже более симпатично. Свериться с результатом, который должен у вас получиться, можно в ветке iteration_5 репозитория, специально подготовленного под текущую серию постов. И не забываем, про возможность просмотра отрендеренного результата на GitHub Pages.

- 50+ докладов и мастер-классов, - 2 дня профессионального общения с 400+ участниками из сотен компаний СНГ, - полезные инсайты и новые знания. Все это — международная конференция для технических писателей TechWriter Days 3 , которая пройдет 27-28 марта в Москве. Мероприятие состоится в гибридном формате — офлайн + онлайн-трансляция. 📚А до 1 сентября можно стать докладчиком. Для подачи заявки на выступление переходите по ссылке. Больше информации для докладчиков вы найдёте здесь

#продолжи_мысль_SE Рецензия на пост «Фронт раньше бэка – это вообще законно?» (автор: Сергей Сапрыкин), который наглядно показывает, как НЕ НАДО выстраивать процессы в IT Пост прямиком из реальной жизни. Зацепил меня он тем, что автор не побоялся (не постеснялся) описать свой факап. Описанная здесь ситуация может должна стать уроком для всех, кто как-то причастен к процессам проектирования, разработки и интеграции. Чем полезен пост Это — наглядный пример того, как делать не надо. И если вы видите, что ситуация на проекте начинает развиваться похожим образом, звоните во все колокола и можете еще всем вокруг показать этот пост в качестве примера. Что смутило в посте Смутило то, что автор вообще в это ввязался и не попытался додавить руководителей, чтобы параллельно выстроить нормальную работу над бэком. В идеале он должен был синхронизировать фронтовые и бэковые процессы, не надеясь, что все как-то само рассосется. Но, как говорится, каждый сам кузнец своего счастья. Какие выводы можно сделать Вывод один. Как сказал один умный человек (правда, не знаю, кто это был): «Не делайте плохо, делайте хорошо». Участвую в конкурсе «Продолжи мысль» от @systems_education