NV
Конечно, не всех получится научить новым инструментам. Но откомментировать мерж-реквест — задача посильная.
Size: a a a
2017 December 20
NV
И ещё мерж-реквесты избавляют от ревью по почте. Вместо того чтобы перекидывать почтой PDF или DOCX, все участвуют в одном централизованном обсуждении. Кстати, в одной из последних версий GitLab добавили комментирование картинок. https://habrahabr.ru/company/softmart/blog/341458/#kommentirovanie-izobrazheniy-ce-ees-eep
NV
Другое дело, что в исходнике легко прокомментировать содержание PDF-ки, а верстку — гораздо сложнее. Для этого я бы предложил скриншоты делать.
NV
Вот ребята из Рестрима рассказывают, что пишут всё в Md, потому что им так удобно и эффективно, а на рецензию отдают DOCX, потому что рецензенты так требуют. https://events.yandex.ru/lib/talks/4970/
NV
> реализацией отдельной системы согласования, где комментарии будут храниться отдельно от HTML
Это был бы очень интересный инструмент. Мы бы такой прикрепили к себе на сайт, чтобы пользователи могли откромментировать содержимое.
Это был бы очень интересный инструмент. Мы бы такой прикрепили к себе на сайт, чтобы пользователи могли откромментировать содержимое.
NV
> и комментариев в нём уже нет
В мерж-реквесте комментарии никуда не пропадают. Рецензент может даже затребовать конкретные изменения — поставить мини-задачи внутри мерж-реквеста. Пока он не отметит, что задачи решены, МР нельзя будет слить.
В мерж-реквесте комментарии никуда не пропадают. Рецензент может даже затребовать конкретные изменения — поставить мини-задачи внутри мерж-реквеста. Пока он не отметит, что задачи решены, МР нельзя будет слить.
NV
Кстати, то, что я называю мерж-реквестом (merge request), многим знакомо под названием пулл-реквест (pull request). Есть некоторое расхождение в терминах.
NV
3. Про артефакты.
Тут важно, кто редактирует артефакты и в каком формате.
Тут важно, кто редактирует артефакты и в каком формате.
NV
Внутренняя документация часто включает в себя схемы, диаграммы Ганта, ссылки на задачи в трекере и т.п. С ними отлично справляется конфлюенс.
NV
Т.е. roadmap я бы охотнее писал в конфлюенсе.
NV
Во внутренней и внешней документации наверняка разные требования.
АГ
Понятно, спасибо. Будем думать дальше. Напишу, если к чему-то интересному придём
NV
Например, у нас все диаграммы для пользовательской документации рисует дизайнер. Мы тоже не можем PlantUML использовать, хотя технически смогли бы.
NV
@PAK3APYKY подведу итог. Документация как код — когда пишут выделенные специалисты, когда есть привязка к версиям продукта, особенно когда можно хранить вместе с кодом. Позволяет поставить разработку документации на одни рельсы с разработкой кода и тесно сотрудничать с разработчиками. В частности, написать тесты, легче привлекать разработчиков к рецензированию и т.п.
NV
Конфлюенс — когда редактировать будет множество людей без специальной подготовки, когда не нужно рецензировать и явно принимать каждое изменение, для интеграции с JIRA. Для внутренней документации компании вроде ТЗ, роадмапов и правил распорядка он отлично подходит.
2017 December 28
EM
Добрый вечер! Подскажите, пожалуйста, где можно почитать про локализацию документации на нескольких яз. Использую github + rtd и изначально доки были на одном яз.(EN). Теперь решено добавить и др. яз. (в том числе RU). Как это сделать красиво на RTD?
NV
Кратко: из документов с помощью
sphinx-intl формируются файлы PO с парами оригинал-перевод. Потом вы их переводите.NV
Можно редактировать просто как текстовый документ, но лучше использовать специальную программу для перевода, потому что в ней будет память переводов. Она поможет переводить консистентно и сэкономит силы.
NV
Есть бесплатные программы, есть платные. Есть ещё сервисы вроде transifex.com и crowdin.com.