🚀 Друзья, 2-ая международная конференция технических писателей TechWriter Days пройдет 28-29 марта 2025 года в Санкт-Петербурге в офлайн и онлайн формате.

‼️Разыгрываем‼️
🎫1 офлайн и 1 онлайн билеты
🎫скидка 50% на 2 офлайн и 2 онлайн билета
🎫скидка 30% на 3 офлайн и 3 онлайн билета

Наш информационный партнер — компания documentat.io и их документационный опрос😉

Как принять участие? Всё просто:
🔹Пройди опрос от нашего партнера, сделай свой вклад в изучение техписательского сообщества!
🔹Вступи в телеграм-группу конференции

⚡️Итоги подведём 25 февраля в этой же группе TechWriter Days!

Станьте частью этого долгожданного события! Ждём вас на Конференции❤️

Все знают, что такое Kubernetes. Правда же?
Но если хотите узнать больше, приходите 27 марта на Deckhouse Conf.

Жизненно

Лампочка сломана — что делать?

Меня в другом канале показывают. Красивое.

Вторая Международная конференция технических писателей TechWriter Days / 2 старутет только послезавтра. Но подписчики моего канала уже сегодня могут воспользоваться полезнотой, которой я поделюсь во время своего доклада про документирование GraphQL API.
Ловите ссылку на репозиторий, который позволит вам потренироваться в документировании GraphQL API. Пользуйтесь и прокачивайте свои скиллы.
А все подробности, фишки и нюансы, касающиеся документирования GraphQL API — во время доклада. Буду рад видеть всех.

Коротко о TW Days 2

Техрайтерс дэйс — огонь конфа.
Здесь только нужная инфа.
Нетворкинг здесь удачно прёт.
Попал сюда — тебе везёт.

Здесь темы под любой запрос.
Мне заскучать здесь не пришлось.
Организация здесь — высший класс.
На афтепати — расколбас.

Спасибо оргам за конфу.
А спикерам — за их инфу.
Участникам — за позитив.
Здесь позитива просто взрыв.

Конфа, уверен, удалась.
Жаль, только, быстро пронеслась.
Нам всем пора на поезд иль на рейс…
До встречи на Техрайтерс дэйс.

Доклады с первой конференции Techwriter Days уже доступны!

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

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

Скорее переходите в наш канал VK Видео и смотрите доклады, которые помогут вам стать ещё круче в профессии. Будем рады вашим отзывам и комментариям!

Моя статья «Документирование HTTP API (и не только) с Foliant», написанная по мотивам доклада на TWD1, попала в шорт-лист «Технотекста-7». Правда, категории про техническую документацию в этом году не было. Но, что есть, то есть.
В общем, вы знаете, что делать.
https://habr.com/ru/companies/habr/articles/906136/

Спите? Ну тогда просыпайтесь!

Я наконец-то сделал это, переформатировал и опубликовал Курс по проектированию и документированию API в виде сайта на Github Pages.

Если вы до этого момента сомневались, стоит ли проходить, хватит сомневаться. Кликайте сюда и проходите курс.

Нашел в закромах

А ведь я когда-то (во времена фрилансерства) даже участвовал в «битве Главреда» (да-да, того самого, «всея руси» который, на букву Иль...хов). Выиграть не получилось. Но опыт был интересный.

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

В общем, результат по ссылке.

О сколько нам открытий чудных... Или передать все эти ваши Террабайты иногда быстрее с помощью грузовика

Читаю сейчас широко известную книгу про сети. И с удивлением для себя обнаружил, что большие объемы информации быстрее (не всегда, а в определенных случаях, конечно же) быстрее передать с помощью… грузовика. И даже сервис есть такой у Amazon.

А я как-то и не задумывался о том, что так можно было.

UPD. Сервис, оказывается уже закрыли (но другие альтернативы остались). Спасибо подписчику за наводку 👍.

Знания лишними не бывают. Особенно, когда они про популярный SSG

А давайте замутим небольшую серию постов про Jekyll и Liquid.

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

Вы в в деле?

Если в деле, ставьте под постом 🔥 (и друзей своих зовите, кому это может быть интересно).
Если нет — ставьте 👀.

#tw_api_jekyll

Привет, как договорились выше, начинаем знакомство с Jekyll и Liquid на практике. Это и серия других постов по теме будут помечены тегом #tw_api_jekyll. В рамках серии постов мы попробуем наладить сборку сайта-справочника API из спецификации в формате OpenAPI.

Сегодня мы подготовим «почву» для нашего справочника.
Для этого выполните следующее:

1. Установите себе на компьютер Jekyll и все зависимости по инструкции для вашей ОС со страницы Installation документации этого SSG (приобнял пользователей Windows — у вас самая длинная инструкция ).

2. Создайте на своем компьютере новый проект с помощью команды (в терминале, консоли).

jekyll new tw_api_jekyll

Здесь вместо tw_api_jekyll можно использовать любое другое имя. Это — имя папки, в которой будет создан новый проект (сайт). Чтобы у нас с вами не было «рассинхрона», предлагаю оставить его как есть.

3. После этого перейдите в созданную папку:

cd tw_api_jekyll

4. Запустите сайт командой:

bundle exec jekyll serve

Если все сделано правильно, сайт с настройками по умолчанию будет доступен по адресу http://localhost:4000.

Откройте папку tw_api_jekyll в файловом менеджере, в IDE или посмотрите ее структуру в консоли (как вам удобно). Вы увидите следующую картину:

tw_api_jekyll /
├── _posts/                         # Папка для постов 
├── _site/                            # Папка со сгенерированными страницами сайта 
├── Gemfile                       # Файл зависимостей Ruby
├── Gemfile.lock              # Конкретные версии зависимостей (генерируется автоматически)
├── _config.yml               # Основной конфигурационный файл
├── .jekyll-cache/           # Кеш для ускорения сборки
├── 404.html                  # Шаблон для станицы 404
├── about.markdown    # Страница about
└── index.markdown    # Главная страница

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

Сделайте следующее:

1. Удалите папку _posts/ и файл about.markdown. Это мы делаем потому, что наш сайт-справочник API будет одностраничным.

2. Переименуйте файл index.markdown в index.md. Делать это не обязательно, с обоими расширениями Jekyll работает без проблем. Давайте считать это вкусовщиной: просто я привык использовать для Markdown-файлов расширение .md.

3. Откройте файл index.md и во фронтметтре (это фрагмент вверху страницы, заключенный в ---) удалите привязку к стандартному шаблону. Для этого удалите layout: home (или закомментируйте, это нам в будущем понадобится).

4. В начало файла index.md добавьте заголовок # Справочник TW_api. Сохраните файл.

Если все сделали правильно, по адресу http://localhost:4000 будет находиться страница с заголовком # Справочник TW_api без какой-либо разметки (т.к. мы «отвязались» от стандартного шаблона).

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

#tw_api_jekyll

Привет. Продолжаем знакомство с Jekyll. В прошлый раз мы «подготовили почву» для нашего сайта-справочника.

Сегодня:

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

1. Добавление шаблона

Чтобы добавить шаблон для нашего сайта, сделайте следующее:

1.1. Создайте в корне директории с сайтом папку _layouts. Именно в ней по умолчанию Jekyll ищет шаблоны для страниц сайта.

1.2. Создайте в этой папке файл api_layout.html со следующим содержимым:

<!doctype html>
<html lang="ru">
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
      {{ content }}
    <footer>
    </footer>
  </body>
</html>

1.3. В файле index.md (его мы создали в прошлый раз и «отвязали» от шаблона по умолчанию), в frontmatter укажите, что для этой страницы будет использоваться шаблон api_layout.html:

---
layout: api_layout
---

2. Добавление спецификации, из которой будет собираться справочник

Чтобы добавить спецификацию, сделайте следующее:

2.1. Создайте в корне репозитория с сайтом папку _data. Это папка, которая предназначенная для хранения структурированных данных в форматах YAML, JSON или CSV. Очень удобно, чтобы разделить контент, который нам нужно рендерить, от шаблонов, скриптов и пр.

2.2. В папке _data создайте файл openapi_spec.yaml.

2.3. В файл openapi_spec.yaml поместите спецификацию (эту спецификацию мы с вами разработали на Курсе по проектированию и документированию API). Скопировать ее можно здесь.

3. Вывод содержимого спецификации на сайт

Чтобы вывести спецификацию на сайт, сделайте следюущее:

3.1. Создайте в корне репозитория с сайтом папку _includes. В Jekyll эта папка используется для хранения переиспользуемых фрагментов кода.

3.2. В папке _includes создайте файл api_reference.liquid. Его как раз мы и будем потом переиспользовать. Здесь будет находиться скрипт для вывода содержимого спецификации на страницу с необходимыми преобразованиями. Подробнее про Liquid — в документации.

3.3. В файл api_reference.liquid добавьте код для вывода содержимого спецификации openapi_spec.yaml на страницу сайта:

{% assign spec = site.data.openapi_spec %}

<div class="schema_wrapper">
  {{ spec }}
</div>

3.4. В файл index.md добавьте код, который как раз и будет переиспользовать наш шаблон api_reference.liquid:

{% include api_reference.liquid %}

При рендеринге страницы Jekyll дойдет до этого кода, увидит там include, пойдет в папку _include и выполнит liquid-скрипт в файле api_reference.liquid.

Готово, если вы все сделали правильно, содержимое спецификации появится на странице сайта (не забываем, что рендеринг запускается командой bundle exec jekyll serve).

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

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