Комментарии 16
А почему не используете родной пакет ttf-mscorefonts-installer ?
Интересно Ваша реализация следующего пути документообновления.
Вы (команда или один человек) готовите документ в asciidoc, затем собираете в формат docx и передаете заказчику (внешний или внутрении) на рассмотрение. Он редактирует документ, добавляет комментарии "на полях" (в которых часто выносятся новые мысли или предполагаемые предложения к правкам) и высылает обновленный docx файл.
И теперь вопросы. Есть ли возможность перевести изменения в репозиторий из формата docx снова в формат asciidoc? Есть возможность не потерять эти комментарии и принять их во внимание?
Подобное обсуждалось здесь в коментариях к серии статей под общим названием "Asciidoc для подготовки сложной документации", например https://habr.com/ru/post/550086/comments/#comment_22886324.
После подготовки финальной версии документа в asciidoc мы конвертируем его в pdf и в таком виде документ уходит в заказы на разработку. Обратно в docx его не преобразуем. Если необходимо вносить изменения в документ может и заказчик используя UI GitLab'а.
Изменение схемы работы с документами (что не будет обмена через e-mail docx документами) было согласовано в том числе и с заказчиком.
Прочитал обе статьи, но так и не понял: что вы с этой "документацией" в итоге делаете?
С Word'ом, xml и т.п. понятны сложности, неудобства и прочая попо-боль, но понятно ради чего: есть небольшое количество соглашений по разметке: описывая пользовательский интерфейс клавиатурные комбинации обозначаем одним стилем, окна/формы - другим, пункты меню - третьим. В итоге "лёгким движением руки" получаем общий справочник клавиатурных комбинаций, а в печатном/гуёвом выводе они красиво отрисованы как кнопочки. Биндим это с файлами локализации - получаем заготовку для переводчика, где все видимые пользователю сущности уже переведены так, как оно есть в продукте.
Реализуем процессы-алгоритмы - в описании размечаем стилями/тэгируем: "контракты", высокоуровневые сущности предметной обрасти, детали реализации, обращения к сторонним компонентам/библиотекам. В итоге можем автоматически получить тезаурус решений для последующего переиспользования, какие-то FAQ по реализациям и использованию внешних компонентов.
AsciiDoc, насколько я понимаю, не подразумевает семантическую разметку, это просто текст слегка обогащённый красивостями.
Как сотрудники отнеслись к такой перемене? Проводили ли какие-то обучения, курсы? Были ли "отказняки", кому вообще не зашло и ни по каким предлогом работать в новом инструменте не хотят?
Команда и заказчик положительно. Sales в начале очень просили ТЗ в docx, но потом просто добавляли ТЗ в виде pdf в заказ.
Обучение было. Мы обычно проводим внутренние meetup'ы когда хотим использовать или внедрять новые технологии или фреймворки в существующих или новых проектах. Плюс это дает возможность обсудить все плюсы/минусы планируемого решения, которые инициаторы идеи не всегда видны.
Есть возможность помещать документацию в файлы исходным кодом? Например как многострочный коммент?
Респект и уважуха авторам за статью и подход к работе.
Есть несколько моментов, которые хочется уточнить
1) Кто вовлечен в активную работу над документацией? Это в полный рост (документация, как код), то есть каждый член команды создает документацию/вносит правки или для этого есть отдельная роль? Роли
2) Интегрирована ли документация в код (хуки/подсказки/...) или пока репозиторий один, но продукты взаимно не пересекаются?
Спасибо!
Мы как раз и хотели, чтобы в создании документации участвовал каждый член команды. Конечно большую часть документации пишет аналитик взаимодействуя с заказчиком, но изменения в ТЗ вносят и инженеры, и разрабочтики и QA. Иногда документ особенно по телеком части полностью прорабатывает и готовит инженер. Все зависит от необходимой детализации при проработки документов. Или например при сдаче интеграции с Bitrix24 необходимый гайд для Bitrix24 готовил разработчик и QA. Описание архитектуры, схемы взаимодейстия между сервисами пишет техлид.
Мы решили документацию хранить в отдельной репе, не связанной с основным кодом. И для каждого проекта своя репа.
Саша, привет.
А как сделать таблицу с авто нумерацией пунктов? Типичный пример таблица по ПМИ...
Есть ли wysiwig редакторы, позволяющие не только видеть результат, но и редактировать в визуальном а не текстовом режиме?
Использование AsciiDoc для управления документацией на проекте (Часть 2)