А «Table of Contents» ты сам пишешь или AsciiDoc добавляет? Если второе, то разберись, как в AsciiDoc сделана локализация.

Оглавление берется из docx-шаблона. В шаблоне Оглавление == Оглавление.
Аскидочные императивы (toc-title) игнорируются.

Привет! Меня зовут Николай Волынкин и я руковожу командой документации Tarantool.

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

Будет полезен опыт разработки, администрирования или работы в техподдержке. Здорово, если вы знакомы хотя бы с Git, командной строкой и языками разметки. Если не знакомы, мы вас научим за пару недель.

Про что мы пишем
— Tarantool («Тарáнтул») — база данных и сервер приложений, работающие в оперативной памяти, то есть очень быстро. В Tarantool можно писать логику обработки данных на языке Lua. Это тоже очень быстро работает и удобно в разработке*.
— Cartridge — конструктор для разработки и управления кластером баз данных.
— Tarantool Data Grid (далее TDG) — платформа для анализа данных, которой удобно пользоваться не-разработчикам.
— Модули Tarantool, коннекторы для разных языков программирования, инструменты для развертывания.

В ближайшие полгода-год вы будете писать в основном про Cartridge и TDG. Про первый мы пишем на английском. Про второй пока что на русском, но есть план перехода на английский. Документацию для новой версии TDG нужно будет писать во многом с чистого листа.

* Пишу упрощенно. Если вы видите тут кучу ошибок, то вы, наверное, разработчик. Для вас есть другая вакансия.

В чем ценность документации
Тарантул — внутренняя разработка компании Mail.Ru Group. Компания использует его во многих своих проектах (например, почта и облачный сервис МСS). Есть и внешние пользователи. Обычно это крупные банки и телекомы.

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

Кто нас читает
— Разработчики в команде Tarantool, в других подразделениях компании и во всём мире. Для них мы пишем про устройство базы данных, разработку приложений на Lua и другой хардкор.
— Разработчики, которые интегрируют Tarantool в другие системы. Для них мы описываем API коннекторов на C++, Python, PHP, Go и Java.
— Администраторы, которые занимаются развертыванием, мониторингом и поддержкой инсталляций Tarantool, Cartridge и TDG. У нас есть Ansible-роль для развертывания «на железо» и оператор для Kubernetes. Про всё это мы тоже пишем.
— Аналитики, которые используют в своей работе веб-интерфейс TDG. Им мы рассказываем про интерфейсы и сценарии в них.

Как мы работаем
Используем подход «документация как код». Пишем исходники документации на языке разметки, версионируем с помощью Git, все задачи и ревью (рецензирование) — на GitHub. Благодаря этому у нас всё публикуется за 10-15 минут, форматирование не ломается, тексты не теряются, картинки не пропадают. Про любую строку можем сказать, кто, когда и зачем её редактировал.

Ядро Tarantool — продукт с открытым исходным кодом. Большая часть исходников документации тоже открыта и лежит на GitHub. Командный стайлгайд ведём в общей документации.

В команде есть свой разработчик. Он делает для нас инструменты и автоматизацию. Проверять корректность разметки и качество документа нам помогают автотесты. Пока что они совсем простые, скоро их будет больше. По сайту собираем пользовательскую аналитику и отзывы, учитываем их при планировании задач. Раньше сами переводили с английского на русский, сейчас внедряем непрерывную локализацию и отдаём переводы на аутсорс.

Если интересны детали — мы используем Sphinx, reStructuredText, немного Markdown, локально собираем в Docker, используем GitLab CI и Travis, но переезжаем на GitHub Actions, в тесты добавим Vale.

Как откликнуться на вакансию
Пишите на n.volynkin@corp.mail.ru с пометкой [Вакансия] в заголовке. Прикрепите резюме в формате PDF или DOCX. Здорово, если добавите ссылки на примеры ваших текстов. С вопросами приходите в личку @nick_volynkin.

> * Пишу упрощенно. Если вы видите тут кучу ошибок, то вы, наверное, разработчик. Для вас есть другая вакансия.

прекрасное

🤗

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

Всё верно. Продумаю формат и условия, станет можно всем.

на мой взгляд, не хватает города вакансии и способа работы (офис/удалёнка)

Точняк )

Понял, что у Pandoc очень плохая документация

отправь им багу

Какое классное описание вакансии! Работодателям бы этот шаблон на заметку. Супер! 👍

Осталось придумать как её озаглавить, "pls fix everything" звучит так себе)

Проблема глобальная, не с одним каким-то недочётом

можно еще "Kill your techwriters" =)

Проблема в том, что основные ф-ии описаны. Те, что часто применимы и на слуху. А вот те, что используются крайне редко....
Например, toc-title ))

Спасибо, я старался. Приходите к нам работать :)

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

Aww, приятно слышать. Я его писал примерно целый рабочий день.

Кстати, да. Мне тоже понравилось.

Очень здорово! Помню как давала в качестве тестового написать что-нибудь про Тарантул и сама писала небольшие заметки))))