Привет!

Что это? Это загадка-анонс в yaml-формате)

Отгадали? Проверяйте себя:

Третий и пока последний поток большого мастер-класса «Docs as code для ребят постарше» состоится с 11 по 29 мая!

Вас ждут:

Знакомство с гит и ssg, ci/cd, plantUML, openAPI и CSS, много практики и разработка собственного документационного проекта! А ещё шесть живых встреч:

1. Что такое Docs as code. Общие понятия
2. GIT для технического писателя
3. Создание домашнего док.проекта
4. Публикация и развитие док.проекта
5. Подключение разных типов документации к проекту
6. Кастомизация стилей док.проекта. Использование единого источника

Хотите принять участие? Пишите в личку @novillero — я буду вас ждать)
Стоимость сравнима с 45 чашками кофе в ресторанчике у дома ☕️☕️☕️

Будьте внимательны и осторожны! Бронь бесплатная, и я никому не пишу первым (только если вы не записывались в лист ожидания)

P.S. Кто уже принимал участие, пишите в комментарии, как вам? Может, ваш отзыв поможет кому-нибудь сделать правильный выбор)

#карьера

Привет!

Отличная новость для всех, кто хочет начать карьеру технического писателя (и не только) : YADRO приглашает на стажировку по более чем 30 направлениям, в числе которых есть и разработка технической документации!

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

И самое классное — вы можете получить оффер и стать сотрудником компании YADRO!

Что делать? Перейдите на сайт, выберите направление и подайте заявку на участие в стажировке. Рекомендую поторопиться — дедлайн уже 3 мая!

И желаю удачи!

#карьера #реклама

Ура!
Спустя почти год наконец-то выходит второй пост рубрики #вопрос_ответ

Какой формат работы с git выбрать для ведения документации в парадигме docs as code?

На мой взгляд, самый подходящий формат работы в гите для документационных проектов небольших команд — github flow

Этот процесс подразумевает наличие одной основной ветки master и нескольких фиче-веток для каждой отдельной задачи.

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

Github flow хорошо подходит для небольших документационных проектов, которые поддерживаются несколькими людьми.

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

Кстати, на следующей неделе мы начинаем последний поток большого мастер-класса «Docs as code для ребят постарше», в рамках которого мы попробуем себя в роли тех.писателя небольшой документационной команды, поработаем с подходом github flow и создадим собственные док.проекты, которые можно использовать как портфолио или личную базу знаний.

Если хотите принять участие, пишите в личку @novillero, успевайте до выходных!

#карьера #практика

Material for MkDocs — это популярный фреймворк для разработки документационных систем, который я активно использую в рабочих, домашних и парарайтерских проектах.

Сейчас при сборке проектов на MkDocs Material выскакивает страшное предупреждение:

⚠️ Warning from the Material for MkDocs team
MkDocs 2.0, the underlying framework of Material for MkDocs, will introduce backward-incompatible changes, including:
× All plugins will stop working – the plugin system has been removed
× All theme overrides will break – the theming system has been rewritten
× No migration path exists – existing projects cannot be upgraded
× Closed contribution model – community members can't report bugs
× Currently unlicensed – unsuitable for production use

А дело в том, что движок MkDocs, на котором работает MkDocs Material, уже пару лет не обновлялся, а его создатели анонсировали новую версию MkDocs 2.0, которая работает на другом топливе и принципиально несовместима с MkDocs Material.

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

Так в этой истории появился Zensical — независимый от сторонних движков инструмент для создания документационных проектов. Он должен вобрать в себя всё лучшее, что было в MkDocs Material, и стать полноценной ему заменой.

Сам MkDocs Material никуда не пропадёт, но его поддержку прекратят в ноябре 2026 года.

Авторы Zensical понимают, как дорог MkDocs Material пользователям, поэтому очень стараются сделать полностью совместимый продукт.

Я, как активный пользователь MkDocs Material, решил протестировать Zensical, чтобы запланировать миграцию своих проектов.

Ну что ж...

Zensical, как любой молодой продукт, далёк от совершенства. Многое пилится и ещё будет пилиться, но это ожидаемо и не страшно.

Но есть одна большая проблема, которая делает работу старых проектов в Zensical почти невозможной.

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

Авторы решили не поддерживать в Zensical старые плагины от MkDocs. Вместо этого они часть плагинов хотят положить в коробку и превратить в базовые функции продукта, а остальное собираются реализовать с помощью новой модульной системы, позволяющей подключать к проекту сторонние модули с дополнительными фичами. На сайте Zensical даже есть план, функциональность каких старых плагинов будут адаптировать в первую и вторую очередь.

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

В таких условиях я не могу перевезти ни один из своих рабочих или домашних проектов на новую платформу.

Выводы

Что же делать? Ведь впереди нас ждёт апокалипсис с появлением нового движка MkDocs 2.0, который сломает все наши док.системы!

Я честно пытался найти подробную информацию о релизе MkDocs 2.0, но не нашёл. Если коротко, там всё очень сложно. Вполне вероятно, что релиз всё-таки состоится и MkDocs 2.0 реально сломает наши проекты, но!

1. Никто не мешает нам пользоваться старой рабочей версией MkDocs (можно прописать в пайплайне сборки установку стабильной версии MkDocs<2.0; в пакете MkDocs Material это ограничение вроде уже прописано)
2. Существует несколько альтернативных форков MkDocs (например, проект со звучным названием ProperDocs) которые будут продолжать развивать классическое mkdocs-сообщество. Есть тот же самый Zensical, который в своё время дорастёт до полноценного рабочего состояния.

Что же решил я? Я решил продолжить пользоваться MkDocs Material, не обновлять MkDocs до версии 2.0 и ждать, когда в Zensical реализуют модульную систему и добавят все необходимые мне функции.

В общем, конец света откладывается, живём и радуемся нашим прекрасным док.проектам на Material for MkDocs!

#практика #docsascode

Привет!

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

По ходу пьесы я начал разбираться с тем, что это вообще такое и для чего оно нужно, стал постепенно погружаться в этот лор и со временем уже мог переводить с языка девопсов на литературный русский все эти непонятные фразочки типа «прокиньте порт», «прокатите ранбук» и «заскейлите параметры».

Но я всё ещё оставался на уровне «поддерживаю беседу, повторяя фразы за другими и с умным видом кивая головой», а хотелось действительно понимать, как это работает.

Стало ясно, что без учёбы не обойтись. Я начал искать подходящие курсы по системному администрированию на разных популярных платформах.

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

Что сказать? Много практики (название говорит само за себя)), много информации, клёвый препод, который ведёт воркшопы. А, ну и сами воркшопы конечно)

Отдельно хочу отметить наличие облачных виртуальных машин с линуксом, на которых можно тренироваться почти без ограничений. Это оказалось самым важным для меня, так как свободного места на ноуте катастрофически не хватает на разворачивание даже скромной виртуалки. В общем, клёво, полезно, удобно.

Есть ли минусы? Конечно. Для меня главным минусом оказалось наличие жёстких дедлайнов с возможностью слететь с курса. К такому мой график оказался не готов 🤪 А вы будьте готовы планировать своё время на обучение, чтобы не оказаться потом в неудобной ситуации)

Справедливости ради, на весь курс всего два жёстких дедлайна, и времени, отведённого на выполнение контрольных работ, вполне достаточно, чтобы успевать в срок.

В общем, продолжаю грызть гранит науки, учусь различать виртуализацию и контейнеризацию друг от друга, разворачивать сервисы и прокидывать доступы.

Очень надеюсь победить не только линукс, но и свою прокрастинацию)

#практика #карьера

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

1. Длииинные тире

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

Просто посмотрите:

Если пайплайн завершился с ошибкой — rts-utility запустится автоматически. Для повторного запуска утилиты необходимо активировать её вручную — учтите это при выполнении отката деплоя.

Ещё ИИ любит использовать тире как авторский знак — там где человек поставит запятую или двоеточие, ИИ влепит длинное тире.

2. Вопросы-пояснения

Если в тексте встречаются подзаголовки в стиле «Что это значит?», «Как это работает?», «Почему так?», самое время насторожиться. Я заметил, что ИИ постоянно пытается всё объяснить, дополнить, разжевать и проглотить за читателя, да ещё и оформляет эти пояснения отдельными блоками-уведомлениями. В нашей документации так не принято — даже если мы что-то объясняем (почему какая-то штука работает именно так), то нативно встраиваем эти объяснения в текст, а не выделяем их цветными рамочками как в школьном параграфе.

3. Эмодзи

Я стараюсь не иметь принципиальных позиций, но честно вам скажу — не люблю использовать смайлики в доке. Для меня это визуальный шум, который только отвлекает от текста. А вот ИИ их очень любит 😍

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

## Решение проблем 🔧

|Проблема⛔️ |Решение💡 |
|-----------|----------|

4. Пробелы в конце строк

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

Вполне пойдёт как опосредованный дополнительный признак, работающий в связке с более серьёзными приметами.

Так, и что теперь?

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

Если вы замечали ещё какие-нибудь характерные признаки нейроконтента, пишите в комментарии, будем делиться опытом ↓↓↓

#практика

Свершилось!

Уже совсем скоро, в четверг 16 июля мы проведём онлайн-митап по технической документации!

Наверняка кто-то сейчас спросил в недоумении: а кто это «мы»?

Отвечаю: мы — это RWB, и мы проводим TechDocs митап!

Впервые на арене! Вас ждут непревзойдённые мастера пера и акулы инструкций! Аксакалы документации поделятся своими практическими кейсами — спешите, спешите, спешите!

Билет всего 4 сольдо Совершенно бесплатно! Регистрируйтесь и подключайтесь к нашей онлайн-трансляции!

Мы ждём вас в четверг 16 июля в 16:00!

---

Фух, вроде привлёк внимание.

Будет действительно интересно — познакомим вас с техническими писателями RWB и расскажем, как мы работаем с документацией и процессами вокруг неё.

Приходите, будем рады вас видеть!

Осторожно! Этот пост душный на пять закрытых форточек из пяти

Недавно я придумывал определения для глоссария. Запнулся на термине «команда»:

Команда — это функциональная единица [название подразделения], которая занимается разработкой, сопровождением и поддержкой сервисов.

С содержанием всё ок, а вот выбранная форма мне никак не давала покоя. Смотрел я на неё и так, и эдак, и не мог понять: что же именно не так?

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

Да, действительно, простая и примитивная ошибка, азы инфостиля. Исправленный вариант звучал так:

Команда — это функциональная единица [название подразделения], которая разрабатывает, сопровождает и поддерживает сервисы.

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

Я думал-думал и понял: всё дело в тонкостях стилистики текста (сейчас будет псевдофилологический разбор в духе Задорнова)

В английском языке много времён. Есть, например, Present Simple, с помощью которого мы можем сообщить какой-то общеизвестный факт или описать регулярные действия:

The team develops services — команда разрабатывает сервисы и занимается этим регулярно. Это в какой-то мере свойство и назначение команды — разрабатывать сервисы.

А есть, например, Present Continuous, с помощью которого мы описываем действия, происходящие прямо сейчас или в определённый момент времени:

The team is developing services — команда именно сейчас разрабатывает какие-то сервисы. Это не её свойство, это фиксация её деятельности в данный момент.

В русском языке у нас всего одно настоящее время, поэтому явно обозначить разницу между свойством и состоянием в данный момент сложно. Но мне показалось, что конструкция «занимается разработкой сервисов» больше соответствует значению «обычно команда занимается тем, что разрабатывает сервисы», а конструкция «разрабатывает сервисы» — значению «команда сейчас разрабатывает сервисы, а что она будет делать потом, неизвестно».

Согласен, этому нет рационального филологического подтверждения, но моё чувство стиля склоняется именно к такой интерпретации, поэтому я с чистой совестью в своём глоссарии оставил первоначальный вариант:

Команда — это функциональная единица [название подразделения], которая занимается разработкой, сопровождением и поддержкой сервисов.

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

TLDR: Вместо исправления канцеляризма я оправдываю его использование на протяжении почти трёх тысяч знаков)))

#карьера

Привет! Как проходит лето?

Если вы хотели встряхнуться и срочно решить какую-нибудь интересную задачку, у меня есть для вас кое-что.

10 августа заканчивается приём заявок на TechWriter Days 4!

Да-да, IV Международная конференция для технических писателей пройдёт в Москве 19–20 марта 2027 года, но задуматься о докладе можно и нужно уже сейчас!

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

* Docs-as-Code, API-документация и автоматизация
* Внедрение нейросетей и AI-инструментов в работе техписа
* Управление знаниями, локализация и UX-редактура
* Инженерные и процессные кейсы в документировании

Торопитесь и подавайте заявку до 10 августа!

#карьера

Какие софт-скиллы приходят вам в голову, когда вы составляете своё резюме? Стрессоустойчивость, коммуникабельность, многозадачность?

Это всё здорово и безусловно полезно, но есть одно не самое очевидное качество, которое очень пригодится техническому писателю — Адаптивность

Представьте, вы организовали процесс документирования в команде, развернули вашу доку в docs-as-code. Всё красиво, хорошо и прекрасно работает.

Но наступает день, когда к вам приходят коллеги (или даже начальство) и говорят: нам не нравится/неудобно/долго пользоваться вашим гитом, мы устали откалывать ветки и мержить мерж реквесты! Мы хотим старый добрый конфлюенс!

И у вас есть два пути: повести себя как хороший родитель или повести себя как эффективный управленец.

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

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

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

Да, бывает больно отказываться от любовно настроенного инструмента, работающего как часы. Но как приятно смотреть на коллег, которым легко и удобно пользоваться твоей докой!

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

Но как прокачать это умение?

Рецепта нет. Есть отличное правило из agile-манифеста, которому я стараюсь следовать:

Люди и их взаимодействие важнее, чем процессы и инструменты

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

Обращайте внимание на тропинки, благоукрашайте свой парк и работайте на радость и комфорт ваших пользователей)

#практика

Друзья, привет!

В первой половине года мы успешно провели три больших мастер-класса по Docs as code.

У меня появилась возможность повторить его ещё раз в сентябре.

Вас ждут:

Два вебинара и четыре воркшопа, на которых мы познакомимся с практиками и инструментами docs as code, научимся работать с git (от клонирования репозитория до решения конфликтов), создадим домашний док.проект по заветам docs as code, настроим его публикацию и обновление с помощью CI/CD и попробуем превратить этот учебный проект в полноценное портфолио, работая с разными типами документации. А ещё мы станем одной техписательской командой и попрактикуемся в кросс-ревью документации.

Изучаемые навыки:

docs-as-code, git, mkdocs material, markdown — основные
openapi, pluntuml, css, ci/cd — дополнительные, задеваемые с какого-нибудь бока для решения практических задач в рамках мастер-класса.

Сколько стоит?

Мастер-класс платный, но стоимость должна вас обрадовать — по прежнему она равнозначна 45 чашечкам кофе в кофейне.

Как записаться?

Есть только один способ — напишите в личные сообщения @novillero — я буду вас ждать)

ВНИМАНИЕ! Я никому не пишу первым, не прошу перевести деньги для подтверждения брони или чего-то подобного — оплатить можно непосредственно перед началом занятий.

Когда состоится мастер-класс?

Мастер-класс состоится с 8 по 25 сентября, но только если наберётся группа. Если группа не наберётся, мы придумаем какой-нибудь другой формат)

#карьера #docsascode

Мастер-класс по docs-as-code

Ребята, привет!

Кто ещё хочет записаться на большой мастер-класс по docs-as-code, напишите мне, пожалуйста, в личку @novillero сегодня в течение дня.

UPD Места ещё есть, приходите до понедельника)

#карьера #docsascode

Привет!

Отличные новости — большой мастер-класс по docs as code состоится, и начнём мы уже завтра!

Если вы ещё хотите к нам присоединиться, запрыгивайте в наш последний вагон и напишите мне сегодня @novillero

Всем хорошего дня!

#карьера #docsascode