PRO_техписательство
556 subscribers
92 photos
1 file
45 links
Канал техписа с дипломами программиста и аналитика. Пишу про техписательство и всё, что около него.
Адепт Docs as code.
До этого 9 лет работал IT-копирайтером и редактором на фрилансе. Так что про фриланс знаю всё. А еще пишу стихи, в т.ч. на заказ.
加入频道
#apidocs

Привет. Продолжаем наш курс.
Сегодня сделаем магию — соберем статический сайт-справочник API из ранее созданной спецификации.

Чтобы магия свершилась, у вас на компьютере должны быть:

1️⃣ Git, чтобы работать с репозиторием со стартерпаком для сборки справочника API.
2️⃣ Docker, чтобы можно было собрать сайт-справочник и посмотреть его локально.

Если (когда) Git и Docker установлены:

1️⃣ Форкните себе репозиторий со стартерпаком для сборки справочника API с Foliant. Для этого у вас должен быть аккаунт на GitLab (процесс создания аккаунта и форка репозитория опустим — с этим предлагаю разобраться самостоятельно).
Когда будете форкать репозиторий, GitLab предложит придумать для него имя (можно оставить как есть). Я свой форк назвал api_docs_foliant_slate_starterpack.
2️⃣ Склонируйте форкнутый репозиторий себе на локальный компьютер.
3️⃣ Откройте репозиторий в любом IDE. И сделайте следующие изменения:
добавьте в корень репозитория файл с расширением .yaml. Имя ему можно дать любое. Я назвал этот файл techwriters.yaml.
скопируйте в созданный на предыдущем шаге файл содержимое итоговой спецификации API (ссылка на нее). Не забудьте сохранить изменения.
найдите в корне репозитория файл foliant.yml. В нем, в строке 8, замените pet_swagger.json на имя файла, который был добавлен в папку на предудщих шагах (в моем случае это techwriters.yaml). Не забудьте сохранить изменения.
4️⃣ Соберите сайт. Для этого запустите терминал (консоль) в папке склонированного репозитория и выполните команду:

docker-compose run --rm foliant make site --with slate

Готово. В случае успешного выполнения команды вы увидите в терминале (консоли) сообщение вроде:


...

Project built successfully.

Done
────────────────────
Result: API.slate/



а в папке склонированного репозитория появится папка API.slate — это и есть наш статический сайт справочник.
Теперь, чтобы посмотреть результат сборки, можете перейти в папку API.slate и открыть файл index.html.

Поздравляю. Вы собрали сайт с дефолтными настройками.

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

БОНУС. При желании можете сразу же опубликовать свой сайт на GitLab pages (в репозитории со стартерпаком есть все настройки для этого). Для этого сделайте коммит с изменениями и запушьте изменения в ветку main (конечно, пушить сразу в main не есть хорошо, но мы же работаем с репозиторием сами и учимся).
Если все хорошо, в разделе Build -> Pipelines вашего репозитория на GitLab появится успешный пайплан (подсвечивается зеленым цветом). А в разделе Deploy -> Pages — ссылка на собранный сайт (см. скрины в комментариях к посту). Мой сайт, например, опубликовался по ссылке.

FYI. Те, у кого получилось задеплоить свой сайт на GitLab pages, оставляйте ссылки в комментариях.
🔥6🤝31
Сегодня пост не по теме курса.
Попалась классная статья про GraphQL — прямо то, что нужно для старта и погружения.
Ох, если бы она была тогда, когда мне пришлось вникать в GraphQL.
В общем, категорически рекомендую.
27👍3
Я только сегодня осознал, что Айтишечка преследовала меня всегда и пыталась засосать в себя. И засосала-таки

На пятом курсе военной академии я выбрал тему диплома «Разработка интерактивного тренажера для обучения личного состава работе с аппаратной … (дальше секретно)». Это была программа (если ее так можно назвать вообще), разработанная с помощью Macromedia Flash 8 и Acrion Script 2.0. Получилось норм. Даже акт внедрения в учебный процесс получил.

Потом Айтишечка напомнила о себе снова, когда пришло время курсовой и дипломной работ жены. Ей я сделал 2 программы (все с помощью тех же Macromedia Flash 8 и Acrion Script 2.0) для работы с детьми (она на дефектолога училась). Программы, кстати тоже активно используют в универе до сих пор.

Затем кривая жизни завела меня в копирайтиг. Но и тут без Айтишечки не обошлось. Со временем я переквалифицировался исключительно на тексты по IT-тематике.
Дальше-больше (или с кем поведешься, от того и наберешься). Я получил вторую вышку с дипломом, в котором написано «Инженер-программист». Тема дипломной работы была «Разработка CRM-системы для учета проектов фрилансера-копирайтера/редактора». Сделал все на PHP+HTML+JavaScript и подружил это дело с базой. По сути, это был одностраничник с табличками, в который подгружались данные о проектах из базы и можно было создавать новые, менять существующие проекты, вести учет финансов и т.д. В отдельном фрейме можно было загрузить и полезные для копирайтера сервисы: glvrd, Advego, Text.ru и etxt.

После универа продолжал работать копирайтером почти 2 года. А потом… Бац — и я работаю техписом в IT. И теперь я понимаю, что это надолго. Ведь это то, чего я хотел: некий симбиоз писателя, программиста и еще каких-то там айтишных специальностей.

Все-таки Айтишечка добилась своего — она меня засосала. И это чертовски приятно осознавать.
🔥16👍10👾3
#apidocs

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

1. Папка slate_shards/basic — здесь хранится шаблон страницы сайта-справочника, JS-скрипты, CSS-файлы и картинки, которые использует бэкенд Slate из состава Foliant для сборки сайта. Т.е. отсюда можно управлять всем, скажем так «фронтендом», нашего справочника.
2. Папка widdershins_templates — здесь хранятся шаблоны, в соответствии с которыми происходит преобразование OpenAPI-спецификации в Markdown, который потом отдается бэкенду Slate для генерации сайта.
Досконально разбираться что за что отвевает в этих папках не будем, при желании можете сделать это самостоятельно. С slate_shards/basic все понятно: открываем собранный сайт, открываем инструменты разработчика в браузере и изучаем селекторы элементов страницы, после чего можно влиять на них посредствам содержимого папки. С шаблонами widdershins_templates поможет разобраться официальная документация Widdershins.

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

Через инструменты разработчика модно увидеть, что левая часть сайта имеет CSS-класс toc-wrapper, а цвет подложки для нее — #2E3336 (черный). Давайте заменим его, например, на цвет с HEX-кодом #5cd8df.
Для этого в файле slate_shards/basic/source/stylesheets/screen.css.scss найдите класс .toc-wrapper, Видно, что для него цвет подложки задан через переменную background-color: $nav-bg;. Можно изменить цвет, заменив значение $nav-bg на #5cd8df или же, заменив значение переменной $nav-bg в файле slate_shards/basic/source/stylesheets/_variables.scss. Если выбрать первый вариант, цвет изменится только для класса .toc-wrapper. Если же изменить значение переменной, тогда цвет изменится для всех классов и элементов, в CSS-правилах которых он используется.
Я изменил значение переменной и цвет применился для подложки левой части сайта, а также для поля ввода формы поиска по сайту (т.к. он задается через ту же переменную $nav-bg в файле slate_shards/basic/source/stylesheets/screen.css.scss).

После внесения изменений не забудьте пересобрать сайт, чтобы увидеть результат.
Теперь вы знаете, как кастомизировать сайт-справочник, собранный с помощью Foliant и Slate. Напоминаю, что только цветами возможности кастомизации не ограничиваются: при должной сноровке вы сможете придать сайту какой угодно вид и даже добавить интерактивности. Рекомендую потренироваться.

В следующий раз разберемся, как документировать API с помощью Foliant и Slate, если спецификации OpenAPI у вас (на проекте) нет, но есть возможность создавать описания методов вручную.
👍8🤝21
#apidocs

Привет.
Публикую очередной (и завершающий) урок курса по документированию API.

Сегодня рассмотрим процесс сборки справочника API, если на проекте нет спецификации в формате OpenAPI.

В таком случае техническому писателю придется:

1. Добыть информацию (у разработчиков, из кода, при самостоятельном тестировании уже разработанного API и пр.).
2. Сделать исходник в формате .md для сборки справочника.
3. Немного изменить конфигурацию в стартерпаке, который мы использовали на предыдущих уроках.

Процесс сбора информации рассматривать не будем, т.к. это отдельный вопрос. Разберемся только с пунктами 2 и 3 из списка выше.

Подготовка исходника для сборки справочника
Как было описано в предыдущем уроке (П.2 списка), Slate собирает сайт-справочник из Markdown-исходника, который получается из OpenAPI-спецификации в результате ее обработки препроцессором swaggerdocWiddershins под капотом). В случае, если OpenAPI-спецификации нет, подготовка этого самого Markdown-исходника ложится на плечи технического писателя.
Я подготовил пример такого исходника с описанием одного метода (ссылка на него) и назвал его api.md.

Некоторые пояснения по нему:

- Первый заголовок первого уровня будет заголовком нашего сайта. Каждый последующий заголовок первого уровня будет восприниматься Slate как заголовок, обозначающий группу методов API (в нашем случае это # techwriters).
- Заголовки второго уровня используются для обозначения методов API (в примере это ## GET /techwriters).
- Текст, который следует после >, и блоки кода рендерятся в правой части сайта.
- При подготовке исходника можно использовать практически любые возможности Markdown, включая таблицы, inline HTML и пр.: Slate все благополучно переварит и сгенерирует сайт-справочник.

Полученный исходник нужно разместить в папке src.

Изменения в конфигурации в стартерпаке

Т.к. сборка сайта будет происходить из уже готового Markdown-источника, нужды в препроцессоре swaggerdoc у нас нет. Поэтому его можно отключить (я просто закомментировал его в foliant.yml для наглядности). Там же, в блоке chapters я изменил исходник, из которого будет собираться сайт.
В общем, это все, что нужно изменить, чтобы собрать сайт-справочник из Markdown-файла.

Можете подтянуть себе ветку reference_without_open_api_spec из репозитория, с которым мы работали на предыдущих уроках (или склонировать репозиторий полностью), если еще не делали этого ранее) и собрать сайт локально, как описано в этом уроке.

К слову, вы можете комбинировать сборку сайта из OpenAPI-спецификации и Markdown-файла одновременно. Как это сделать, описано в документации Foliant. Если интересно, можете попробовать самостоятельно.


На этом всё, курс закончен.

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

Или не всё? Если захотите, в качестве бонусного урока можем рассмотреть, как «замокать» наш API с помощью Postman. Это будет полезным, например, для разработчиков и тестировщиков и поможет им на наглядном примере понять в первом приближении, как будет работать спроектированный API. Если есть такое желание, пишите в комментариях.
🔥9👍3🤝1
Итоги года (а как же без них?):

- Попробовал себя в роли спикера. Выступил на TW Days 1 и мне понравилось (надеюсь, что слушателям тоже). Готовлю доклад для TW Days 2.
- Довольно много путешествовал с семьей на авто (за год около 35 000 км пробега получилось).
- Получил диплом системного аналитика. И даже поработал несколько месяцев СА.
- Сменил работу (получилось как-то внезапно, спонтанно, внепланово). Пока нравится.
- Купип сапборд. Доволен как слон. Правда, во время последнего в сезоне заплыва утопил очки👓.
- Получил 336 новых подписчиков на канал. Пожалуй, это один из главных и значимых для меня итогов: значит, кому-то интересна моя писанина. Спасибо за то, что читаете канал. В следующем году постараюсь радовать подписчиков новыми интересными и полезными постами (почаще).

С наступающим 2025 годом!!! Всем желаю «сбычи мечт», чтобы список итогов в 2025 году был длинным и состоял только из приятных пунктов.
22🔥8
Решил размяться перед первым рабочим днем и доделать презентацию к докладу на TW Days 2.
Тяжеловато, скажу я вам, запускается мозг после продолжительных праздников.
Надеюсь, кураторам доклад зайдет.
1😁13👨‍💻3🔥2
Осталось всего 2 месяца до TechWriter Days #2. Программа уже сформирована. Интересных докладов будет много. Потихоньку формирую для себя список тех, на которые пойду.
🔥3
Программа конференции TechWriter Days #2 сформирована! 🎉

Вас ждут 60+ докладов и мастер-классов, 2 дня профессионального общения с 400+ участниками из сотен компаний СНГ, полезные инсайты и новые знания!

Станьте частью этого важного события, которое состоится 28-29 марта в Санкт-Петербурге по адресу ул. Стартовая 6, лит. А, отель Airportcity Plaza🙏🏼

⚡️билеты
⚡️афиша
⚡️скидки
⚡️видео

Ждем вас на TechWriter Days #2! 🚀
🔥5👍1
Forwarded from Техпис говорит | Подкасты (Anna Kostyagina)
С Днем технического писателя, друзья и коллеги!
Ведь сегодня 2 февраля - 33-й день года ✨️

#праздник #деньтехписателя
🥰12
Говорят, сегодня день технического писателя. Ну что же, ловите несколько строк, посвященных нам с вами:

Одни по ГОСТу пишут доку.
Другие пишут доку на «АПИшки».
Одни всё собирают «Диплодоком».
Другие «Вордом» мучают нервишки.

Одни читают код и парсеры ваяют.
Другие из стейкхолдеров достанут что угодно.
Одни в большущих «Госах» обитают.
Другим в стартапах просто превосходно.

Одни лишь пишут только руководства.
Другие за докопсов поработать бы не против.
Одни в IT, другие — на каком-то производстве.
Кто-то из них болтун, другой не разговорчив.

Все это про техписов, без которых
Хороших доков быть не может просто.
Про новичков совсем и про матёрых.
Про «докс эс кодников» и про адептов ГОСТа.

Сегодня их поздравить не забудьте.
Ведь это же совсем несложно.
Техписы, вы всегда такими будьте.
Такими, без которых невозможно!
122🔥12👏3👎1
А как вы проводите выходные?

Эти у меня получились довольно продуктивными.
Добил курс на «Степике», который купил еще в прошлом сентябре, и получил сертификат.

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

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

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

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

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

Станьте частью этого долгожданного события! Ждём вас на Конференции❤️
5👍32
Все знают, что такое Kubernetes. Правда же?
Но если хотите узнать больше, приходите 27 марта на Deckhouse Conf.
👍1
This media is not supported in the widget
VIEW IN TELEGRAM
🔥4👏3😁3
Дорогие женщины! Хочу поздравить вас с 8 марта.
Позравление предлагаю получить самостоятельно.

Для этого просто «дерните ручку» API (c HTTP-глаголом GET) через Postman или другим удобным способом:

https://virtserver.swaggerhub.com/denmaloyreb/8_march/1.0.0/greeting/NUMBER

Вместо NUMBER подставьте число от 1 до 20.

А самые смелые могут, не побоюсь этого слова, курлануть:

curl --location '
https://virtserver.swaggerhub.com/denmaloyreb/8_march/1.0.0/greeting/NUMBER'

Здесь тоже вместо NUMBER подставьте число от 1 до 20.

Полученными поздравлениями предлагаю делиться в комментариях к посту. Хотя, просто реакции от вас будет тоже достаточно.
Please open Telegram to view this post
VIEW IN TELEGRAM
🔥8❤‍🔥4👏2😍2😁1
Жизненно
Лампочка сломана — что делать?
😁15💯4