И это есть уже! Тоже хорошая, важная штучка!

Используется гиф или какая-либо другая анимация, чтобы показать элементы интерфейса и совершаемые над ними действия? Если это уместно, то мне как пользователю оч приятно и удобно)

Мне тоже очень это нравится. Пока нет, не используется. Но я бы с удовольствием начала бы юзать.
А мне ещё нравится, когда делают гиф-ки с упрощенным интерфейсом.

🔥

Может быть кто может припомнить красивые примеры оформления примеров, глоссариев, how-to блоков и Q&A блоков на док. порталах?
Или вот примеры любимых API references?

#вакансия #техническийписатель #удаленно #wanted_tw

Вакансия: Technical Writer
Компания: Arenadata https://www.youtube.com/watch?v=RKZ7Chty98Y&t=38s
Локация: 100% удаленно (или можно работать в офисе в Москве)
Заработная плата: от 150 тыс. руб. на руки и выше

Что сейчас есть:
- документация на русском языке
- все сборки документации в формате rST и собираются sphinx-doc

Что надо делать:
- собирать информацию у архитекторов, аналитиков и разработчиков
- самостоятельно изучать наши продукты и проходить все описываемые действия на тестовых стендах
- разрабатывать и актуализировать документацию на английском языке
- применять подход Docs as a Code

Кого мы ищем:
- 5+ лет опыта работы техническим писателем
- большой опыт написание различной технической документации на современные IT-продукты (БД, продукты с микросервисной архитектурой, бэкенд, фронтэнд и тд)
- опыт написания документации для разных категорий пользователей
- знание GitHub, опыт с движками генерации статических сайтов и с различными легковесными языками разметки
- опыт работы в консоли, знание Linux на уровне опытного пользователя
- знание английского языка на хорошем уровне для написания документации (Upper Intermediate минимум)

Плюсом будет:
- опыт написания документации на распределённые системы (например, БД, блокчейн)
- опыт программирования на Java/C++
- опыт работы с Antora и Asciidoc
- знание инструментария CI/CD, Docker для задач технической документации

Условия:
Официальное оформление по ТК РФ, белая ЗП;
Cертификация и обучение за счет компании;
Возможность работы удаленно и гибкий график;
Обеспечение техникой для работы (ноутбук, монитор);
Корпоративные курсы английского;
ДМС со стоматологией.

✉️ Контакты: @pankina_hr poe@arenadata.io

самые классный API, на мой взгляд — на базе Swagger UI https://petstore.swagger.io/

На мой взгляд, удобнее всё-таки three-column layout для таких целей. Но это с точки зрения техписателя. Как удобнее разработчикам я без понятия

Если используете в доке gif, то можно прикрутить gif player

вот такие имеете в виду? https://www.aerisweather.com/support/docs/api/reference/endpoints/#most-popular

Вот такие:
https://stripe.com/docs/api/charges/create
https://slatedocs.github.io/slate/#authentication

* Навигация (список методов)
* Описание
* Код

для Slate есть ещё тема DocuAPI,  чуть-чуть покрасивше и с добавлением мультиязычности https://docuapi.netlify.app/

Swagger подкупает интерактивностью и тем, что ему можно скормить готовую спецификацию OpenAPI

Списки литературы в док файлах не сильно удобно.

Сделал реп на гитхабе.
https://github.com/holamgadol/beginners-guide-to-technical-writing

Предлагаю туда добавлять новое

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

А в чате есть писатели из Arenadata? Плюс вам за Sphinx/rST, давайте делиться опытом )

а что вы имеете в виду?

есть) но мы переходим на антору со сфинкса

но это же не мешает вам делиться знаниями по сфинксу)

нет) если я вижу вопрос по сфинксу, на который знаю ответ, то как правило, я отвечаю

Как раз возник вопрос по reST

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

Я пишу так:

1. Откройте
2. Выполните

.. include:: install.rst
   :start-line: 30
   :end-line: 108

В результате получаю:

1. Откройте
2. Выполните
5. Создайте