Да, а нам костюм, конечно, хорошо, но главное, чтоб его удобно было надеть. ))) И галстук не так чтоб сильно был нужен, зато вот пуговички надо сделать именно того цвета, что хочется.
Но есть ощущение, что все системы docops строятся на очень большой доле индивидуальных моментов, которых никто и никогда не опишет.
Решение интересное, спасибо за наводку. Попробуем посмотреть, где и как можно применить.
Я, наверное, о главном пока не сказал, мы не работаем с госзаказчиками, все наши клиенты - это частные компании, хотя и очень крупные. Итог следующий - мы вам платим много денег за ПО, а вы делаете его так чтоб нам понравилось, в т.ч. и документацию. В итоге у нас нет как такового требования по следованию ГОСТам. Конечно мы за основу берем структуру документов из 19-й и 34-й серий, но изначально требований по оформлению именно в таком виде мы не имеем, не говоря уж о рамочках и т.п. тонкостях. А дальше идем к заказчику и дорабатываем на его ландшафте материалы и вот в этот момент появляются требования, которые иногда могут значительно отличаться на проектах - где-то безопасники лютуют и требуют совершенно четкую структуру, которая подходит им; где-то говорят - сделайте нам комикс, т.к. с продуктом будут работать мужики-операторы, которые включить-то комп боятся, не говоря уже о работе со сложными материалами и т.д., и т.п. В общем в итоге рождается структура документации в целом типовая, но немного отличная на разных проектах.
Поэтому я со своей стороны просто вижу решение именно такое: 1. Репа с небольшими файликами маркдаун с информацией по продукту, причем, чем более дробная эта информация, тем лучше; 2. Два параллельных пайплайна, на одном из которых формируется структура портала и выкладывается онлайн, а на втором формируется набор документов в необходимой структуре в форматеПДФ, например. Желательно, чтобы структура была максимально гибкая, чтоб ее менять на лету; 3. На портале есть кнопка или ссылка на импорт отчуждаемых форм документации.
По факту мы сейчас такое решение и получили, вот надо его донастроить.
Да, у нас специфика - это внедрение продукта в небольшом количестве, но на очень крупных объектах у заказчиков, типа, Лукоил, НЛМК, ГПН и т.п. Поэтому часто продукт дорабатывается под заказчика и такие изменения не всегда тиражируются и вот тут у нас вступают в противоречие математика затрат на зарплату техписа и внедрение технологии, и, к сожалению, не всегда такая математика в пользу технологии. Все понимают, что надо, что это классно хорошо и удобно, но внедрение стоит дороже, чем выхлоп от проекта. И вот в таких реалиях приходится балансировать команде. Поэтому мы сейчас дорабатываем решение, чтобы оно удовлетворяло и продуктовым и проектным реалиям.
Лично мой подход - это организованный портал с ролевой моделью доступа и авторизацией, который доступен онлайн и тогда мы все потребности закрываем и docops просто идеален, но конкретные проектные реализации не всегда позволяют решение сделать именно таким.
Да в том то и дело, что инерция не от техписов идет. Как-раз они то и ЗА всеми руками и ногами. Инерция идет от заказчика через руководство проектов. Первоначальная-то цель все-таки вообще отказаться от отчуждаемого формата документации - читайте на портале, там все новее и свежее и, главное, быстрее, но, при этом, мы же понимаем, что банально структура документации в веб-репрезентации и в виде отчуждаемого ПДФ-документа должна быть различной. Итог - необходимость формирования двух пайплайнов сборки, на одном из которых будет формироваться html и портал, а на другом набор docx, которые можно отдать заказчику в соответствии с его требованиями. Тут еще момент связан с тем, что при работе с большими заказчиками в рамках базовых функций продукта частенько возникает некоторая доля кастомных материалов под данный проект, которые нигде не повторяются. Так, для отдельного проекта наша платформа может представить, к примеру, сервис мнемосхем, но, при этом, непосредственно заказчик, будет иметь дело со сложной мнемосхемой, которая разработана исключительно для него, и его в такой ситуации слабо интересует документация по мнемосхемам в целом, т.к. он с ней работать не будет, а вот именно эта схема ему нужна вдоль и поперек расписанная и виде пдф-файла, т.к. читать будет оператор, который к порталу доступа не имеет, да еще и переиспользовать эти материалы мы не имеем права - вот так и получается ситуация, когда на отдельном проекте docops вроде как и не очень применим, т.к. вести отдельную ветку с отдельным пайплайном видится не очень эффективным в плане затрат - один техпис-джун или допом к нему еще команда девопсов и поддержки. Такой вот нюанс, но противный, иногда мешает.
Да, вообще процесс перехода на технологически иные процессы документирования вещь весьма непредсказуемая в плане внедрения - никогда не знаешь где и что вылезет и будет мешать. Но, учитывая особенности самого процесса перехода, понимаю, что данный процесс привязать к какой-либо системе не прокатит. У каждого будут свои болячки и проблемы - кто-то долго будет входить в технологии, кто-то долго перестраивать процессы и переучивать персонал. Вот и у нас такая ситуация - вроде все все понимают и есть модель по переходу, но нет зрелости взглядов, да и заказчик часто давит своими потребностями, что также периодически сбивает с пути. Поэтому команда полностью ЗА переход и хочет работать в новых реалиях, а руководство говорит, что "Вы ребята, конечно, молодцы, но делаем по-старому". )))
Далеко не всегда так. Если мы внедряемся на больших промышленных объектах, где конечным пользователем документации является не инженер и даже зачастую не опытный пользователь ПК, а какой-нибудь лаборант, которому намного проще и быстрее открыть "бумажную" инструкцию, или речь идет об объектах, где и доступа к внешним сетям нет по правилам инфобеза и других ведомств. В таких условиях переложить мышление и разработки и команды техписов на новый лад очень трудно. И доказать, что docops - это полезно, как минимум, занимает огромное время.
Добрый день! Присоединяюсь к Юлиному комментарию. Про наш подход docs as code написано вот здесь https://habr.com/ru/companies/zyfra/articles/578486/. А более подробная статья выйдет в ближайшее время, т.к. переход пока не до конца осуществлен, но обязательно поделимся нашими наработками. надеюсь, будет полезно и интересно.
Коллеги, прошу прощения за критику, но в данной статье изначально поставлен некорректный вопрос. Автор явно сталкивался с работой переводчиков без нормальных постановок на работы. Такое сплошь и рядом и при таком подходе, конечно, иногда термины лучше не трогать вообще, т.к. переводчик, как минимум чаще всего недостаточно компетентен в вопросах тонкостей тех или иных значений.
Если же говорить по-человечески, то терминологическая работа над текстом осуществляется не в рамках перевода текста. Это отдельный вид работ, когда на основе текста составляется полные его тезаурус, все термины выверяются в соответствии с нормами и стандартами, согласуются с заказчиком и только потом уходят в текст. Причем данная работа осуществляется перед выполнением перевода, а не во время. Тогда переводчик получает готовый перечень терминологии и может корректно все перевести.
В комментариях выше была отсылка, что банально заказчик за данную работу платить на хочет, вот и все. Дороговато это, т.к. отплата пословная, а времени требуется много.
В большинстве компаний, к сожалению и в нашей тоже частенько, не проводится терминологическая работа над ПО и продукт наполняется всевозможными профессионализмами и т.п. мусором от как-раз таки разработчиков так, что заказчик потом прекрасно себе дает "отлупы" именно за терминологию. Хотя разработчики тоже сетуют, что перевод терминов нежелателен.
При работе над терминами мы должны помнить следующие простые вещи:
Мы русские люди и говорим по-русски, следовательно, переводиться должно все что может перевестись.
При выполнении перевода терминологии необходим заблаговременный выстроенный процесс диалога между заказчиком и переводчиком по обсуждению и согласованию терминологии.
В статье нет ни одной ссылки на нормы по переводу, а ведь он есть и в большом количестве начиная от наших "любимых" ГОСТов и заканчивая современными руководствами по стилю (упомяну хотя бы материалы таких компаний как Майкрософт, SAP, Google и т.п.). И вот там то переводы уж точно выполнены "серьезными парнями" и прошли вагончик согласований и сверки. Как показывает практика, разработчики их тоже часто не читают и даже не знают о них ))).
Термин может оставаться англоязычным и калькированным и т.п. Но он должен быть одинаковым по всему тексту и укладываться в рамки технических норм. Главное помнить, что в англоязычном варианте термины также многозначны и какой-нибудь банальный click имеет три варианта перевода. И вот когда вы все это свалите в кашу, вот тут то и получите полный набор всех недосказанностей англоязычной корпоративной терминологии, т.к. она именно корпоративная и требует от пользователя знакомства именно со стандартом корпорации. И тот факт, что вы хорошо знакомы с ним и вам "удобно" им пользоваться вовсе не означает такой же картины со стороны другого пользователя этой же документации.
Инженер тем и отличается от бригадира, что уровень образования его несколько выше уровня подчиненных и он способен терминологическую работу провести сам. А "нытье" разработчиков, к сожалению, зачастую вызвано именно отсутствие должного уровня подготовки в области языка, что делает их довольно-таки однобокими. Как инженеры они обязаны владеть терминами на своем языке, и если им проще работать с англоязычной терминологией, то зачастую вопрос не к терминологии, а к образованию.
Вот когда мы соблюдаем принцип sapienti sat и ведем нормальную терминологическую работу, мы получаем корректную терминологическую картину. И у нас не возникнет ситуации, в которой я лично оказывался именно из-за терминологии, когда один очень крупный заказчик сказал: "Видимо, наши инженеры говорят на разных языках", что не сорвало проект, но потребовало дополнительного полугода работ по устранению противоречий в терминах.
Вы поднимаете вечную проблему, с которой бизнесовая или девелоперская сторона часто приходят, говоря "Зачем нам техписатель, если мы прекрасно можем обойтись и без него, т.к. самим все приходится писать", и техпис тупо правит за нами текст.
Тут важно учитывать одну тему - технический писатель - это специалист по разработке и оформлению документации. Он чаще всего самостоятельно не создает контент (контент создает разработчик, аналитик, проектировщик и т.п.); он его формирует и превращает в осмысленный документ, в соответствии со стандартами, понятный широкому читателю и пользователю продукта.
Опыт показывает, что документация, которая разрабатывалась без участия технических писателей однобока и часто плохо принимается заказчиком, т.к. писатель таки специалист с грамотным и хорошим языком. Вот в этом его функция.
Да, согласен, конечно, "на вкус и цвет...". Я бы, со своей колокольни, порекомендовал подумать в сторону концепции документирования docs as part of development team, частью которой является docs as code, и подумать над тем, как плотнее включить писателей в процесс разработки - это к "если эти люди вне команд разработки и имеют слабое представление об устройстве разрабатываемого продукта" - просто тогда будет значительно меньше узких мест с актуализацией документации.
Спасибо за ответ. Но тогда как-то пропадает необходимость переноса пользовательской документации в репозитории, и вести доки для внутреннего пользования действительно удобнее в конфлюенс, и все материалы, содержащие пользовательские истории, скриншоты и т.п. проще держать во внутренней базе знаний с настроенными макросами для переиспользования, цитирования и др., а для обеспечения консистентности проще назначить пару хороших редакторов, которые будут отслеживать процессы разработки и обновления ПО. Это будет дешевле, и не надо париться над репозиториями, мердж-реквестами, черепиками и другим шаманством. Опять же, не надо дополнительно обучать сотрудников. Все-таки docs as code - это парадигма работы с внешним заказчиком и с интернет-ресурсами.
Добрый день! Интересная статья, но в обозначенной проблеме я вижу один важный пробел, касающийся медленного и тяжелого развития docs as code в Вашем случае. Создается впечатление, что изначальная цель ведения документации в таком формате не обозначена. Для чего вообще требуется держать доки рядом с кодом? Я бы для начала сконцентрировался именно на вопросах необходимости переноса документации в репозитории из конфлюенс - это первый момент, который рекомендуют при начале подобных действий. Доки в гите - вещь сложная и неоднозначная. В нашей компании (Zyfra) мы осознали данную необходимость, в первую очередь, в связи с тем, что CI/CD - это наш основной процесс доставки кода клиенту, вместе с ним уходят и доки, разворачиваются в виде портала у заказчика, плюс портал развернут на наших серверах и мы можем его сделать доступным из глобальной сети. В данном случае вопрос заполненности репозиториев картинками не очень актуален, не так уж они много месте жрут. Зато есть быстрый и удобный инструмент работы с доками без необходимости выдачи доступов и т.п. танцев с бубном. Кстати, такой вопрос, а как Вы даете пользователям доки из конфлюенс? Или каждый раз при необходимости экспортируете?
Да, было бы очень логично и классно сделать набор материалов, с последовательным рассмотрением всех особенностей от общих основ до конкретной реализации в рамках проекта.
Нет, это лишь пример того, как документация может быть организована. Смысл данного решения - организация документации по тем же принципам, что и исходный код и связанные с ним элементы, так чтобы документы можно было собрать и отобразить в каком-либо одном месте или выгрузить и передать.
Если перейдете на другие страницы ссылки, там будут и другие документы. И все они многостраничные с перекрестными ссылками, рисунками, схемами и т.п.
А что касается возможности извлечения документов, это уже вопрос индивидуальной настройки ресурса, наш настроен и позволяет выгрузить документ.
У нас она собирается на соответствующем ресурсе в сети, к которому настраивается доступ, и где ее можно в любой момент посмотреть и получить. Наши документы в открытом доступе не лежат, но в качестве примера можно привести такую страничку - https://developers.xsolla.com/subscriptions-api/. Принцип аналогичный.
Добрый день! Подробное рассмотрение вопроса публикации документации в данном подходе просто не вошло в статью ввиду значительного объема материала. Если вкратце, то подход docs as code предполагает, что документация готовится для размещения онлайн, и у нас имеется соответствующий инструмент, который собирает материалы в ветках гита и публикует их, после чего материалы доступны заказчику и другим заинтересованным лицам. С самого ресурса документация может быть скачана в необходимом формате, для этого как-раз и используется утилита Pandoc, которая конвертирует документы в те форматы, которые необходимы и обладает достаточно широкими способностями для настройки, например, позволяет применить для оформления документа корпоративный шаблон.
В случае же с доставкой документа непосредственно заказчику, документ собирается в соответствии с теми же процедурами, с которыми происходит сборка образа программы и т.п. вещи. При этом заказчику нет нужды читать документ, содержащий информацию по всем сервисам продукта, которые ему не поставляются, он получает только документ, который соответствует тем сервисам, которые развернуты у него. А дальше документ может уже передаваться в той форме, которая необходима самому заказчику, например, может быть экспортирована в ворд или предоставлена в виде Html, или размещена в том же конфлюенс и т.п.
Что же касается вопроса использования конфлюенс - тут есть базовые проблемя для размещения документации, которые никто не решил: 1. Доступ к документам (размещать у себя и давать доступ для заказчика? Не очень разумный вариант, т.к. в этом случае вы пустите в свою базу знаний сторонних лиц, которым там, может быть, и незачем находиться); 2. Размещение документов на ресурсах заказчика ( а если заказчик не пользуется конфлюенс? Экспорт из него ну вот никак нельзя назвать нормальным - это весьма проблемный документ, который требует очень глубокой проверки и доработки, т.к. из него часто банально пропадают изображения и схемы, а кроме этого такой документ невозможно оформить в соответствии с требованиями заказчика, например, в его корпоративном шаблоне. Также, заказчик вполне может применять в своей работе какую-нибудь иную вики-базу, x-wiki например, которая тоже весьма проблематично взаимодействует с конфлюенсом. А наш подход позволяет создать документ в таком формате и разметке, который является универсальным и легко может быть подготовлен для импорта в системы заказчика, либо просто может быть передан через CI.
Да, согласен, но тут есть проблема в первую очередь в количестве задач. Одна команда - один писатель, это, конечно, хорошо, но когда писателей 10, а команд вдвое больше? И количество параллельно разрабатываемых сервисов более 200, становится просто нереально проводить по каждому апдейту встречи и все обсуждать (лучше автоматизировать эти процессы, а встречи оставить как важные вспомогательные элементы взаимодействия).
Плюс есть еще один очень важный момент - клиенты, мы разрабатываем документацию для конкретных клиентских решений, которые хоть немножко, но отличаются, и требуют дополнительных доработок, а кроме того клиентская документация реализована в различных форматах, начиная от банальных вордовских файлов и заканчивая вики- и html-версиями. Тут тоже образуется значительный пул доработок, которые в определенный момент требуют фактически перестройки всей страницы на портале у заказчика, и это потребность в огромном количестве времени.
Поэтому, на мой взгляд, все-таки лучше автоматизировать максимум того, что можно автоматизировать, чтобы эффективнее использовать труд писательской команды, не заставляя их мотаться по бесконечным встречам и бесконечно перерисовывать шрифты и картинки в документах.
Добрый вечер! На самом деле ничто не мешает. просто Ваша модель документирования опирается на другой инструмент и больше соответствует docs as service - это так же рабочая модель, и так же применяется. Просто если у Вас в процессе какого-либо этапа разработки возникнет изменение или дополнение, то пока вы не посадите техписа рядом, он не узнает об этом, а когда до него дойдет постановка, пока он разберется, пока напишет и донесет до команды. Такая модель хорошо работает, когда у вас идеально отработан процесс постановки задач писателям, а если нет? А как быть, когда ваш продукт развивается на глазах и когда новые фичи становятся базовыми сервисами в течение одного-двух дней, ждать митинга с писателем? Docs as code работает, и когда команда не успела ему сообщить, банальные уведомления приходят.
Да, а нам костюм, конечно, хорошо, но главное, чтоб его удобно было надеть. ))) И галстук не так чтоб сильно был нужен, зато вот пуговички надо сделать именно того цвета, что хочется.
Но есть ощущение, что все системы docops строятся на очень большой доле индивидуальных моментов, которых никто и никогда не опишет.
Решение интересное, спасибо за наводку. Попробуем посмотреть, где и как можно применить.
Я, наверное, о главном пока не сказал, мы не работаем с госзаказчиками, все наши клиенты - это частные компании, хотя и очень крупные. Итог следующий - мы вам платим много денег за ПО, а вы делаете его так чтоб нам понравилось, в т.ч. и документацию. В итоге у нас нет как такового требования по следованию ГОСТам. Конечно мы за основу берем структуру документов из 19-й и 34-й серий, но изначально требований по оформлению именно в таком виде мы не имеем, не говоря уж о рамочках и т.п. тонкостях. А дальше идем к заказчику и дорабатываем на его ландшафте материалы и вот в этот момент появляются требования, которые иногда могут значительно отличаться на проектах - где-то безопасники лютуют и требуют совершенно четкую структуру, которая подходит им; где-то говорят - сделайте нам комикс, т.к. с продуктом будут работать мужики-операторы, которые включить-то комп боятся, не говоря уже о работе со сложными материалами и т.д., и т.п. В общем в итоге рождается структура документации в целом типовая, но немного отличная на разных проектах.
Поэтому я со своей стороны просто вижу решение именно такое: 1. Репа с небольшими файликами маркдаун с информацией по продукту, причем, чем более дробная эта информация, тем лучше; 2. Два параллельных пайплайна, на одном из которых формируется структура портала и выкладывается онлайн, а на втором формируется набор документов в необходимой структуре в форматеПДФ, например. Желательно, чтобы структура была максимально гибкая, чтоб ее менять на лету; 3. На портале есть кнопка или ссылка на импорт отчуждаемых форм документации.
По факту мы сейчас такое решение и получили, вот надо его донастроить.
Да, у нас специфика - это внедрение продукта в небольшом количестве, но на очень крупных объектах у заказчиков, типа, Лукоил, НЛМК, ГПН и т.п. Поэтому часто продукт дорабатывается под заказчика и такие изменения не всегда тиражируются и вот тут у нас вступают в противоречие математика затрат на зарплату техписа и внедрение технологии, и, к сожалению, не всегда такая математика в пользу технологии. Все понимают, что надо, что это классно хорошо и удобно, но внедрение стоит дороже, чем выхлоп от проекта. И вот в таких реалиях приходится балансировать команде. Поэтому мы сейчас дорабатываем решение, чтобы оно удовлетворяло и продуктовым и проектным реалиям.
Лично мой подход - это организованный портал с ролевой моделью доступа и авторизацией, который доступен онлайн и тогда мы все потребности закрываем и docops просто идеален, но конкретные проектные реализации не всегда позволяют решение сделать именно таким.
Да в том то и дело, что инерция не от техписов идет. Как-раз они то и ЗА всеми руками и ногами. Инерция идет от заказчика через руководство проектов. Первоначальная-то цель все-таки вообще отказаться от отчуждаемого формата документации - читайте на портале, там все новее и свежее и, главное, быстрее, но, при этом, мы же понимаем, что банально структура документации в веб-репрезентации и в виде отчуждаемого ПДФ-документа должна быть различной. Итог - необходимость формирования двух пайплайнов сборки, на одном из которых будет формироваться html и портал, а на другом набор docx, которые можно отдать заказчику в соответствии с его требованиями. Тут еще момент связан с тем, что при работе с большими заказчиками в рамках базовых функций продукта частенько возникает некоторая доля кастомных материалов под данный проект, которые нигде не повторяются. Так, для отдельного проекта наша платформа может представить, к примеру, сервис мнемосхем, но, при этом, непосредственно заказчик, будет иметь дело со сложной мнемосхемой, которая разработана исключительно для него, и его в такой ситуации слабо интересует документация по мнемосхемам в целом, т.к. он с ней работать не будет, а вот именно эта схема ему нужна вдоль и поперек расписанная и виде пдф-файла, т.к. читать будет оператор, который к порталу доступа не имеет, да еще и переиспользовать эти материалы мы не имеем права - вот так и получается ситуация, когда на отдельном проекте docops вроде как и не очень применим, т.к. вести отдельную ветку с отдельным пайплайном видится не очень эффективным в плане затрат - один техпис-джун или допом к нему еще команда девопсов и поддержки. Такой вот нюанс, но противный, иногда мешает.
Да, вообще процесс перехода на технологически иные процессы документирования вещь весьма непредсказуемая в плане внедрения - никогда не знаешь где и что вылезет и будет мешать. Но, учитывая особенности самого процесса перехода, понимаю, что данный процесс привязать к какой-либо системе не прокатит. У каждого будут свои болячки и проблемы - кто-то долго будет входить в технологии, кто-то долго перестраивать процессы и переучивать персонал. Вот и у нас такая ситуация - вроде все все понимают и есть модель по переходу, но нет зрелости взглядов, да и заказчик часто давит своими потребностями, что также периодически сбивает с пути. Поэтому команда полностью ЗА переход и хочет работать в новых реалиях, а руководство говорит, что "Вы ребята, конечно, молодцы, но делаем по-старому". )))
Далеко не всегда так. Если мы внедряемся на больших промышленных объектах, где конечным пользователем документации является не инженер и даже зачастую не опытный пользователь ПК, а какой-нибудь лаборант, которому намного проще и быстрее открыть "бумажную" инструкцию, или речь идет об объектах, где и доступа к внешним сетям нет по правилам инфобеза и других ведомств. В таких условиях переложить мышление и разработки и команды техписов на новый лад очень трудно. И доказать, что docops - это полезно, как минимум, занимает огромное время.
Добрый день! Присоединяюсь к Юлиному комментарию. Про наш подход docs as code написано вот здесь https://habr.com/ru/companies/zyfra/articles/578486/. А более подробная статья выйдет в ближайшее время, т.к. переход пока не до конца осуществлен, но обязательно поделимся нашими наработками. надеюсь, будет полезно и интересно.
Коллеги, прошу прощения за критику, но в данной статье изначально поставлен некорректный вопрос. Автор явно сталкивался с работой переводчиков без нормальных постановок на работы. Такое сплошь и рядом и при таком подходе, конечно, иногда термины лучше не трогать вообще, т.к. переводчик, как минимум чаще всего недостаточно компетентен в вопросах тонкостей тех или иных значений.
Если же говорить по-человечески, то терминологическая работа над текстом осуществляется не в рамках перевода текста. Это отдельный вид работ, когда на основе текста составляется полные его тезаурус, все термины выверяются в соответствии с нормами и стандартами, согласуются с заказчиком и только потом уходят в текст. Причем данная работа осуществляется перед выполнением перевода, а не во время. Тогда переводчик получает готовый перечень терминологии и может корректно все перевести.
В комментариях выше была отсылка, что банально заказчик за данную работу платить на хочет, вот и все. Дороговато это, т.к. отплата пословная, а времени требуется много.
В большинстве компаний, к сожалению и в нашей тоже частенько, не проводится терминологическая работа над ПО и продукт наполняется всевозможными профессионализмами и т.п. мусором от как-раз таки разработчиков так, что заказчик потом прекрасно себе дает "отлупы" именно за терминологию. Хотя разработчики тоже сетуют, что перевод терминов нежелателен.
При работе над терминами мы должны помнить следующие простые вещи:
Мы русские люди и говорим по-русски, следовательно, переводиться должно все что может перевестись.
При выполнении перевода терминологии необходим заблаговременный выстроенный процесс диалога между заказчиком и переводчиком по обсуждению и согласованию терминологии.
В статье нет ни одной ссылки на нормы по переводу, а ведь он есть и в большом количестве начиная от наших "любимых" ГОСТов и заканчивая современными руководствами по стилю (упомяну хотя бы материалы таких компаний как Майкрософт, SAP, Google и т.п.). И вот там то переводы уж точно выполнены "серьезными парнями" и прошли вагончик согласований и сверки. Как показывает практика, разработчики их тоже часто не читают и даже не знают о них ))).
Термин может оставаться англоязычным и калькированным и т.п. Но он должен быть одинаковым по всему тексту и укладываться в рамки технических норм. Главное помнить, что в англоязычном варианте термины также многозначны и какой-нибудь банальный click имеет три варианта перевода. И вот когда вы все это свалите в кашу, вот тут то и получите полный набор всех недосказанностей англоязычной корпоративной терминологии, т.к. она именно корпоративная и требует от пользователя знакомства именно со стандартом корпорации. И тот факт, что вы хорошо знакомы с ним и вам "удобно" им пользоваться вовсе не означает такой же картины со стороны другого пользователя этой же документации.
Инженер тем и отличается от бригадира, что уровень образования его несколько выше уровня подчиненных и он способен терминологическую работу провести сам. А "нытье" разработчиков, к сожалению, зачастую вызвано именно отсутствие должного уровня подготовки в области языка, что делает их довольно-таки однобокими. Как инженеры они обязаны владеть терминами на своем языке, и если им проще работать с англоязычной терминологией, то зачастую вопрос не к терминологии, а к образованию.
Вот когда мы соблюдаем принцип sapienti sat и ведем нормальную терминологическую работу, мы получаем корректную терминологическую картину. И у нас не возникнет ситуации, в которой я лично оказывался именно из-за терминологии, когда один очень крупный заказчик сказал: "Видимо, наши инженеры говорят на разных языках", что не сорвало проект, но потребовало дополнительного полугода работ по устранению противоречий в терминах.
Вы поднимаете вечную проблему, с которой бизнесовая или девелоперская сторона часто приходят, говоря "Зачем нам техписатель, если мы прекрасно можем обойтись и без него, т.к. самим все приходится писать", и техпис тупо правит за нами текст.
Тут важно учитывать одну тему - технический писатель - это специалист по разработке и оформлению документации. Он чаще всего самостоятельно не создает контент (контент создает разработчик, аналитик, проектировщик и т.п.); он его формирует и превращает в осмысленный документ, в соответствии со стандартами, понятный широкому читателю и пользователю продукта.
Опыт показывает, что документация, которая разрабатывалась без участия технических писателей однобока и часто плохо принимается заказчиком, т.к. писатель таки специалист с грамотным и хорошим языком. Вот в этом его функция.
Да, согласен, конечно, "на вкус и цвет...". Я бы, со своей колокольни, порекомендовал подумать в сторону концепции документирования docs as part of development team, частью которой является docs as code, и подумать над тем, как плотнее включить писателей в процесс разработки - это к "если эти люди вне команд разработки и имеют слабое представление об устройстве разрабатываемого продукта" - просто тогда будет значительно меньше узких мест с актуализацией документации.
Спасибо за ответ. Но тогда как-то пропадает необходимость переноса пользовательской документации в репозитории, и вести доки для внутреннего пользования действительно удобнее в конфлюенс, и все материалы, содержащие пользовательские истории, скриншоты и т.п. проще держать во внутренней базе знаний с настроенными макросами для переиспользования, цитирования и др., а для обеспечения консистентности проще назначить пару хороших редакторов, которые будут отслеживать процессы разработки и обновления ПО. Это будет дешевле, и не надо париться над репозиториями, мердж-реквестами, черепиками и другим шаманством. Опять же, не надо дополнительно обучать сотрудников. Все-таки docs as code - это парадигма работы с внешним заказчиком и с интернет-ресурсами.
Добрый день! Интересная статья, но в обозначенной проблеме я вижу один важный пробел, касающийся медленного и тяжелого развития docs as code в Вашем случае. Создается впечатление, что изначальная цель ведения документации в таком формате не обозначена. Для чего вообще требуется держать доки рядом с кодом? Я бы для начала сконцентрировался именно на вопросах необходимости переноса документации в репозитории из конфлюенс - это первый момент, который рекомендуют при начале подобных действий. Доки в гите - вещь сложная и неоднозначная. В нашей компании (Zyfra) мы осознали данную необходимость, в первую очередь, в связи с тем, что CI/CD - это наш основной процесс доставки кода клиенту, вместе с ним уходят и доки, разворачиваются в виде портала у заказчика, плюс портал развернут на наших серверах и мы можем его сделать доступным из глобальной сети. В данном случае вопрос заполненности репозиториев картинками не очень актуален, не так уж они много месте жрут. Зато есть быстрый и удобный инструмент работы с доками без необходимости выдачи доступов и т.п. танцев с бубном. Кстати, такой вопрос, а как Вы даете пользователям доки из конфлюенс? Или каждый раз при необходимости экспортируете?
Да, было бы очень логично и классно сделать набор материалов, с последовательным рассмотрением всех особенностей от общих основ до конкретной реализации в рамках проекта.
Нет, это лишь пример того, как документация может быть организована. Смысл данного решения - организация документации по тем же принципам, что и исходный код и связанные с ним элементы, так чтобы документы можно было собрать и отобразить в каком-либо одном месте или выгрузить и передать.
Если перейдете на другие страницы ссылки, там будут и другие документы. И все они многостраничные с перекрестными ссылками, рисунками, схемами и т.п.
А что касается возможности извлечения документов, это уже вопрос индивидуальной настройки ресурса, наш настроен и позволяет выгрузить документ.
У нас она собирается на соответствующем ресурсе в сети, к которому настраивается доступ, и где ее можно в любой момент посмотреть и получить. Наши документы в открытом доступе не лежат, но в качестве примера можно привести такую страничку - https://developers.xsolla.com/subscriptions-api/. Принцип аналогичный.
Добрый день! Подробное рассмотрение вопроса публикации документации в данном подходе просто не вошло в статью ввиду значительного объема материала. Если вкратце, то подход docs as code предполагает, что документация готовится для размещения онлайн, и у нас имеется соответствующий инструмент, который собирает материалы в ветках гита и публикует их, после чего материалы доступны заказчику и другим заинтересованным лицам. С самого ресурса документация может быть скачана в необходимом формате, для этого как-раз и используется утилита Pandoc, которая конвертирует документы в те форматы, которые необходимы и обладает достаточно широкими способностями для настройки, например, позволяет применить для оформления документа корпоративный шаблон.
В случае же с доставкой документа непосредственно заказчику, документ собирается в соответствии с теми же процедурами, с которыми происходит сборка образа программы и т.п. вещи. При этом заказчику нет нужды читать документ, содержащий информацию по всем сервисам продукта, которые ему не поставляются, он получает только документ, который соответствует тем сервисам, которые развернуты у него. А дальше документ может уже передаваться в той форме, которая необходима самому заказчику, например, может быть экспортирована в ворд или предоставлена в виде Html, или размещена в том же конфлюенс и т.п.
Что же касается вопроса использования конфлюенс - тут есть базовые проблемя для размещения документации, которые никто не решил: 1. Доступ к документам (размещать у себя и давать доступ для заказчика? Не очень разумный вариант, т.к. в этом случае вы пустите в свою базу знаний сторонних лиц, которым там, может быть, и незачем находиться); 2. Размещение документов на ресурсах заказчика ( а если заказчик не пользуется конфлюенс? Экспорт из него ну вот никак нельзя назвать нормальным - это весьма проблемный документ, который требует очень глубокой проверки и доработки, т.к. из него часто банально пропадают изображения и схемы, а кроме этого такой документ невозможно оформить в соответствии с требованиями заказчика, например, в его корпоративном шаблоне. Также, заказчик вполне может применять в своей работе какую-нибудь иную вики-базу, x-wiki например, которая тоже весьма проблематично взаимодействует с конфлюенсом. А наш подход позволяет создать документ в таком формате и разметке, который является универсальным и легко может быть подготовлен для импорта в системы заказчика, либо просто может быть передан через CI.
Спасибо. Интересно, надо слазить внутрь конфы. Честно говоря, как-то не задавался такими способами.
Да, согласен, но тут есть проблема в первую очередь в количестве задач. Одна команда - один писатель, это, конечно, хорошо, но когда писателей 10, а команд вдвое больше? И количество параллельно разрабатываемых сервисов более 200, становится просто нереально проводить по каждому апдейту встречи и все обсуждать (лучше автоматизировать эти процессы, а встречи оставить как важные вспомогательные элементы взаимодействия).
Плюс есть еще один очень важный момент - клиенты, мы разрабатываем документацию для конкретных клиентских решений, которые хоть немножко, но отличаются, и требуют дополнительных доработок, а кроме того клиентская документация реализована в различных форматах, начиная от банальных вордовских файлов и заканчивая вики- и html-версиями. Тут тоже образуется значительный пул доработок, которые в определенный момент требуют фактически перестройки всей страницы на портале у заказчика, и это потребность в огромном количестве времени.
Поэтому, на мой взгляд, все-таки лучше автоматизировать максимум того, что можно автоматизировать, чтобы эффективнее использовать труд писательской команды, не заставляя их мотаться по бесконечным встречам и бесконечно перерисовывать шрифты и картинки в документах.
Добрый вечер! На самом деле ничто не мешает. просто Ваша модель документирования опирается на другой инструмент и больше соответствует docs as service - это так же рабочая модель, и так же применяется. Просто если у Вас в процессе какого-либо этапа разработки возникнет изменение или дополнение, то пока вы не посадите техписа рядом, он не узнает об этом, а когда до него дойдет постановка, пока он разберется, пока напишет и донесет до команды. Такая модель хорошо работает, когда у вас идеально отработан процесс постановки задач писателям, а если нет? А как быть, когда ваш продукт развивается на глазах и когда новые фичи становятся базовыми сервисами в течение одного-двух дней, ждать митинга с писателем? Docs as code работает, и когда команда не успела ему сообщить, банальные уведомления приходят.
Интересная мысль, но честно говоря, не очень себе представляю, как поженить md и конфлюенс? Или там все-таки отображается только ссылка?