Size: a a a

DocOps-сообщество

2021 March 17

NK

ID:0 in DocOps-сообщество
Если что, этот вопрос не про технологии, он про управление процессом разработки документации и её перевода.

Есть цель: хорошие доки на английском, проверенные на корректность и язык. Они полностью переведены на русский и перевод тоже проверен на корректность и язык.

Такая цель никогда не будет достигнута на 100%, потому что продукты постоянно развиваются и документация тоже должна идти вперёд. Поэтому цель на самом деле другая: непрерывно писать и переводить документацию по продуктам, делая самое важное с использованием ограниченных ресурсов, поддерживая установленный уровень качества и выполняя другие обязательства.

Есть ресурсы, которыми эта цель достигается: техписатели, переводчики, ревьюеры со стороны разработки. Есть производственный процесс и его этапы: исследование задачи, разработка документации, ревью, перевод, обновление.

Эти этапы можно выстроить по-разному. Дать больше работы тем или другим. Думаю, что нужно следовать теории ограничений: находить узкие места в критической цепи, разгружать и усиливать их. Но как это делать, когда есть несколько направлений работы? И можем ли мы рассматривать себя как изолированную систему и оптимизироваться без учета всей разработки продуктов? Наверное, не можем.

Всё это мне пока что очень непонятно, но очень интересно. Давайте соберемся и обсудим? Например, в эту пятницу, 19 марта, 16:00 Мск. Ссылку на созвон кину в чат незадолго до встречи.
источник

NV

Nick Volynkin in DocOps-сообщество
Anton Tatsienko
+ к этому накрутить версионирование и когда появляется новая версия оригинального текста - можно создавать таску на перевод
Возможно, мы придём к тому, что будем отправлять строки на перевод прямо из фиче-ветки документации, потом добавлять в неё же перевод и мержить/публиковать всё вместе. Но это будет только когда переводы дойдут до 100%.
источник

T

Tapot in DocOps-сообщество
ID:0
У меня сейчас есть интересная дилемма по организации работы над переводом. Чтобы её объяснить, сначала расскажу про механику перевода.

Перевод устроен так: исходный текст нарезается на единицы перевода (translation units, TU). Заголовки, абзацы, пункты списков, ячейки в таблицах. Каждый юнит переводится целиком. Переводить куски текста большего размера — неэффективно, а если нарезать ещё меньше, то потеряется смысл.

Внутри системы переводы хранятся в структуре ключ-значение (ассоциативный массив, dictionary, map). Оригинальный текст — это ключ, а перевод — значение.

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

Как вы думаете, что происходит, когда перевод уже есть, но вдруг поменялся оригинальный текст? Мы ищем по новому ключу, значения там нет, перевод «слетает».

Представьте, что есть старый текст на английском. Его написали давно, но ещё не перевели. Его нужно когда-то перевести, и когда-то вычитать и поправить язык, стиль и оформление.

Можно переводить как есть, когда-нибудь потом вычитывать английский текст, а потом допереводить ещё раз. Получается лишняя работа переводчика.

А ещё можно вычитывать оригинал до перевода. Тогда у переводчика меньше работы, но мы добавляем техписателям срочных задач, которые блокируют работу над переводом. И эти задачи конкурируют за время с другими, более важными задачами по документации.

Кажется, что оба варианта плохи, но второй — хуже. А можно как-то иначе? Отдать пруфрид переводчику или другому внештатному сотруднику? Что бы вы сделали?
А через MT может до 100% догнать?
источник

T

Tapot in DocOps-сообщество
ID:0
У меня сейчас есть интересная дилемма по организации работы над переводом. Чтобы её объяснить, сначала расскажу про механику перевода.

Перевод устроен так: исходный текст нарезается на единицы перевода (translation units, TU). Заголовки, абзацы, пункты списков, ячейки в таблицах. Каждый юнит переводится целиком. Переводить куски текста большего размера — неэффективно, а если нарезать ещё меньше, то потеряется смысл.

Внутри системы переводы хранятся в структуре ключ-значение (ассоциативный массив, dictionary, map). Оригинальный текст — это ключ, а перевод — значение.

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

Как вы думаете, что происходит, когда перевод уже есть, но вдруг поменялся оригинальный текст? Мы ищем по новому ключу, значения там нет, перевод «слетает».

Представьте, что есть старый текст на английском. Его написали давно, но ещё не перевели. Его нужно когда-то перевести, и когда-то вычитать и поправить язык, стиль и оформление.

Можно переводить как есть, когда-нибудь потом вычитывать английский текст, а потом допереводить ещё раз. Получается лишняя работа переводчика.

А ещё можно вычитывать оригинал до перевода. Тогда у переводчика меньше работы, но мы добавляем техписателям срочных задач, которые блокируют работу над переводом. И эти задачи конкурируют за время с другими, более важными задачами по документации.

Кажется, что оба варианта плохи, но второй — хуже. А можно как-то иначе? Отдать пруфрид переводчику или другому внештатному сотруднику? Что бы вы сделали?
Там и модельку на существующем можно свою уже научить
источник

VS

Vadim Smelyanskiy in DocOps-сообщество
Max
Оригинальный текст как ключ это плохое решение. Представление о том, что в переводе фрагменты переведенного однозначно соответствуют фрагментам переводимого - неверно.
Пользуясь случаем, хочу поделиться системой перевода, в которой прям хорошо учтены отличия языков
https://www.projectfluent.org/
источник

NV

Nick Volynkin in DocOps-сообщество
Tapot
А через MT может до 100% догнать?
Есть на примете такой вариант, но пока не исследовали. Вопрос, что больше выбесит читателей: когда перевода нет или он частичный, либо когда он явно машинный и плохой.
источник

T

Tapot in DocOps-сообщество
Так оба варианта можно сделать + фидбек на плохой перевод собрать. Ну и мне кажется, для тех документации на доученной модельке сейчас должно неплохо выходить по качеству
источник

M

Max in DocOps-сообщество
Vadim Smelyanskiy
Пользуясь случаем, хочу поделиться системой перевода, в которой прям хорошо учтены отличия языков
https://www.projectfluent.org/
А можно, если кратко, в чём преимущества перед ICU, или ARB, скажем?
источник

VS

Vadim Smelyanskiy in DocOps-сообщество
Max
А можно, если кратко, в чём преимущества перед ICU, или ARB, скажем?
С ICU тут сравнение подробное
https://github.com/projectfluent/fluent/wiki/Fluent-and-ICU-MessageFormat

Хотя для меня лично важнее всего, что реализации Fluent'а субъективно удобнее
источник

VS

Vadim Smelyanskiy in DocOps-сообщество
Про ARB не знаю, речь про Flutter'овский формат перевода?
источник

M

Max in DocOps-сообщество
Ну, Гугл его продвигает как глобальный, но да, сейчас это Flutter в основном.
источник

M

Max in DocOps-сообщество
Просто если fluent это Mozilla foundation, то сравнение напрашивается.
источник

VS

Vadim Smelyanskiy in DocOps-сообщество
Max
Ну, Гугл его продвигает как глобальный, но да, сейчас это Flutter в основном.
Честно говоря, у меня из-за этого сразу скепсис возник(

Команда Flutter'а много странных вещей пытается сделать глобальными: Dart, Flutter for Web (Hummingbird)
источник

M

Max in DocOps-сообщество
Посмотрел спецификации - референсы выглядят полезно, но привязывают переводы к общему контексту. Функции выглядят опасно. Собственный текстовый формат вместо JSON или YAML кажется избыточным решением - они подразумевают, что переводчик будет работать в блокноте вместо специализированного интерфейса?
источник

VS

Vadim Smelyanskiy in DocOps-сообщество
Max
Посмотрел спецификации - референсы выглядят полезно, но привязывают переводы к общему контексту. Функции выглядят опасно. Собственный текстовый формат вместо JSON или YAML кажется избыточным решением - они подразумевают, что переводчик будет работать в блокноте вместо специализированного интерфейса?
Согласен, это самое слабое место сейчас

Инструментарий откровенно говоря никакой
https://www.projectfluent.org/play/
источник

VS

Vadim Smelyanskiy in DocOps-сообщество
Vadim Smelyanskiy
Честно говоря, у меня из-за этого сразу скепсис возник(

Команда Flutter'а много странных вещей пытается сделать глобальными: Dart, Flutter for Web (Hummingbird)
А, я к чему про скепсис

Есть у кого-нибудь опыт использования использования ARB вне Flutter'а?
источник

M

Max in DocOps-сообщество
Vadim Smelyanskiy
А, я к чему про скепсис

Есть у кого-нибудь опыт использования использования ARB вне Flutter'а?
Мы даже во флаттере ICU используем)
источник

iv

iakov v in DocOps-сообщество
ID:0
У меня сейчас есть интересная дилемма по организации работы над переводом. Чтобы её объяснить, сначала расскажу про механику перевода.

Перевод устроен так: исходный текст нарезается на единицы перевода (translation units, TU). Заголовки, абзацы, пункты списков, ячейки в таблицах. Каждый юнит переводится целиком. Переводить куски текста большего размера — неэффективно, а если нарезать ещё меньше, то потеряется смысл.

Внутри системы переводы хранятся в структуре ключ-значение (ассоциативный массив, dictionary, map). Оригинальный текст — это ключ, а перевод — значение.

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

Как вы думаете, что происходит, когда перевод уже есть, но вдруг поменялся оригинальный текст? Мы ищем по новому ключу, значения там нет, перевод «слетает».

Представьте, что есть старый текст на английском. Его написали давно, но ещё не перевели. Его нужно когда-то перевести, и когда-то вычитать и поправить язык, стиль и оформление.

Можно переводить как есть, когда-нибудь потом вычитывать английский текст, а потом допереводить ещё раз. Получается лишняя работа переводчика.

А ещё можно вычитывать оригинал до перевода. Тогда у переводчика меньше работы, но мы добавляем техписателям срочных задач, которые блокируют работу над переводом. И эти задачи конкурируют за время с другими, более важными задачами по документации.

Кажется, что оба варианта плохи, но второй — хуже. А можно как-то иначе? Отдать пруфрид переводчику или другому внештатному сотруднику? Что бы вы сделали?
Вообще в отношении перевода действует принцип garbage in — garbage out. то есть если на входе некачественный текст (с неудачным стилем, с фактическими ошибками, и так далее), то и на выходе получится неудачный текст, в общем случае нельзя улучшить переводом то, что исходно было плохо. Поэтому, мне кажется, переводчику следует отдавать уже production ready текст, так мы по крайней мере оптимизируем работу переводчика.
источник

МВ

Михаил Влазнев... in DocOps-сообщество
Всем привет. Может, кто-нибудь поделится опытом, как в компании пишется документация для взаимодействия с мобильными разработчиками на вебсокеты и пуши. Для rest api кажется хватает спецификации openapi, а вот что делать с этими двумя вещами, ума не приложу. (:
источник

IA

Ivan Abashkin in DocOps-сообщество
ID:0
Если что, этот вопрос не про технологии, он про управление процессом разработки документации и её перевода.

Есть цель: хорошие доки на английском, проверенные на корректность и язык. Они полностью переведены на русский и перевод тоже проверен на корректность и язык.

Такая цель никогда не будет достигнута на 100%, потому что продукты постоянно развиваются и документация тоже должна идти вперёд. Поэтому цель на самом деле другая: непрерывно писать и переводить документацию по продуктам, делая самое важное с использованием ограниченных ресурсов, поддерживая установленный уровень качества и выполняя другие обязательства.

Есть ресурсы, которыми эта цель достигается: техписатели, переводчики, ревьюеры со стороны разработки. Есть производственный процесс и его этапы: исследование задачи, разработка документации, ревью, перевод, обновление.

Эти этапы можно выстроить по-разному. Дать больше работы тем или другим. Думаю, что нужно следовать теории ограничений: находить узкие места в критической цепи, разгружать и усиливать их. Но как это делать, когда есть несколько направлений работы? И можем ли мы рассматривать себя как изолированную систему и оптимизироваться без учета всей разработки продуктов? Наверное, не можем.

Всё это мне пока что очень непонятно, но очень интересно. Давайте соберемся и обсудим? Например, в эту пятницу, 19 марта, 16:00 Мск. Ссылку на созвон кину в чат незадолго до встречи.
Если честно, я не очень понял изначальную твою дилемму.
Она между тем, чтобы возложить дополнительную работу либо на переводчика, либо на техписателя? Почему выполнение этой дополнительной работы плохо? Кто является бутылочным горлышком в твоей системе: техписатель или переводчик?
Могу предложить сформулировать по ней грозовую тучу. Например:
Я должен освободить переводчика от дополнительной работы для того чтобы A
Я должен освободить техписателя от дополнительной работы для того  чтобы B
И A и B мне нужно для того чтобы ...
Я не могу делать и то и другое одновременно потому что ...

Критическая цепь из теории ограничений это больше про классическое управление проектами. Если ты способен расписать заранее большинство этапов работ и плюс-минус предсказать вариативность по этим работам.
Для интеллектуальной работы часто очень сложно оценить длительность и понять следующий этап. В интеллектуальной работы вариативность достаточно высокая. Если у вас много проектов, и вы можете и делаете их предварительное планирование, то вы можете использовать CCPM для планирования работ и загрузки. Для этого вам нужно выпровнять все проекты друг за другом по критической цепи. Ресурсы на критической цепи не должны пересекаться.

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

Здесь я могу предложить Канбан-метод. И первое что нужно сделать, это понять как именно вы выполняете входящие запросы, в каком порядке и приоритете.  В этом может помочь такой инструмент как STATIK.
источник