Комментарии 6
4 недели - это сильно! Про техническую часть понятно, любопытно узнать процессные нюансы:
Как долго онбордите новичков без опыта в dac? Быстро втягиваются?
Как готовите драфты статей? Если писать сразу в языке разметки, фокус уходит в оформление, а не смысл. Есть ли централизованный подход?
Как проводите ревью? Через мерж реквесты?
Где и как решаете конфликты? Прямо в гитлабе?
Что делают техписы, когда возникают ошибки? У вас в команде остался инженер или ребята сами справляются?
Все нюансы познаются с течением времени, но первые коммиты случаются обычно в течение нескольких дней, причем с минимальным участием наставника. Помогает образцовый документ и инструкции.
Обычно сразу в языке разметки. Так уходит меньше времени на последующее оформление, да и сложностей с отвлечением от сути, честно говоря, не наблюдается.
Ревью техническими писатели — через mr-ы, владельцами знаний — через mr, конфлюенс-аутпут, комментариями в баг-трекере. Подбираем инструмент под удобство и навыки вычитывающих.
Конфликты решаем на локальной машинке, используем стандартные средства гита+редактор (в нашем случае — vs code).
Если ошибки на уровне пайпов в гитлабе/инфраструктуры — привлекаем девопса. Если на уровне сборки — ребята справляются сами или с помощью внутреннего сообщества технических писателей.
Юра, спасибо большое за статью, было очень интересно читать эдакий process journey.
Решением проблемы стал ,возможно, не очень изящный, но рабочий способ — скрипт, который запускал сборку документации два раза подряд.
Если сможешь, поправь, пожалуйста, запятую, опосля **стал**.
Еще такой вопрос, почему был выбран именно RST, а не asciidoc в качестве формата?
Спасибо за комментарий!
Отчасти раскрывал вопрос в комментариях к предыдущей статье:
Основное — отсутствие встроенного локализационного контура (в rst это генерация po из коробки) и большая распространенность rst, включая поддержку сообщества (субъективно на базе доступных расширений и ответов на наши вопросы на просторах интернета).
Спасибо, было очень интересно, буду перенимать ;)
Вопрос и пара дополнений:
А можете ли вы поделиться образцовый документом?
Кстати, Sphinx отлично собирается и на Винде, без докера. Но это скорее вопрос удобства.
Тексты кстати могут быть и на Markdown, Sphinx через расширение умеет его читать.
Ну и на выходе можно сделать отлично брендированный PDF и даже экзотику типа CHM ;)
Создание системы документирования, или как в Cloud.ru от «ворда» к docs as code за месяц переходили. Часть 2