Локализация документации

[Olegas]

Хочу поднять тему локализации документации API.

Понятно, что можно просто скопировать текущие md и переводить их.

Как отслеживать изменения в основной документации? Можно ли это хоть как-то автоматизировать? Есть ли у кого-нибудь опыт в организации такого процесса?

[gko]

предлагаю это обсудить на встрече(см. #16). У них документация вся вроде по версиям идет — то есть с новым релизом появляются новые доки. Можно завести json с переводом и оригиналом для каждого раздела и сделать таску которая будет сравнивать оригинал с текущими доками на сайте и показывать для каких методов описание изменилось.

[Olegas]

Можно попробовать автоматизировать через webhooks, добавленные на основной реп iojs. Ловить комиты с правкой документации и автоматом генерировать issue в этом репе.

[isRuslan]

Ссылка по теме: nodejs/iojs.org#33
Думаю, лучшее что можем сделать это перевод документации.
С генерацией, автоматизацией и хуками повременим.

[nkt]

Мне кажется надо форкнуть основные доки, а переводы выделить в ru папку, на пример. Затем подтягивать изменения, и актуализировать перевод.

[Olegas]

Как форкнуть доки, если мы - не форк основного репа?
Или сделать отдельный для документации?
Что даст форк? Упростим получение патчей к исходникам?

[nkt]

Конечно. Вроде перевод доков рельсов так делают. Следить за изменениями всегда проще, когда их накатываешь сам 😉

То есть я предлагаю сделать так: форкаем, переводим. Как только перевод полностью готов - обновляем из оригинала и опять полностью переводим изменения. Никакого рассинхрона быть не должно.

[YurySolovyov]

Хорошо было бы глянуть что делают другие группы

[gko]

Другие пока переводят сайт и выкладывают в виде mdшек, а затем постят в твиттер, что перевели какой-то раздел.
Я предлагаю сделать переводы и одновременно сделать таску, которая бы собирала сайт, который мы будем постить раз в неделю на github pages, при этом там над каждым разделом сделать ссылку «original», чтобы коммюнити могло сразу увидеть и написать, что перевод неправильный.
А также таску, которая бы делала форк последних док и сравнивала оригиналы с нашими.

[Olegas]

Можно без таски. Можно сделать вебхук и повесить его на основной реп iojs. Хук отловит пуши, проанализирует их, и напишет таски в этот реп на перевод нового.
Я могу заняться этим.

[gko]

в любом случае завтра пообщаемся на эту тему. Я могу заняться настройкой этой фигулины.

[Olegas]

Подготовил PR #19
Структура такая

/doc
  /api
    *.md - документация
    .docs - SHA комита из iojs/io.js, с которого скопирована документация
  /api_assets - css, js
  template.html - шаблон
/tools
  /doc - утилиты для сборки json/html
    README.md - интересное про структуру документации
/out
  /doc
    /api - здесь появится документация после сборки
Makefile - используем make чтобы собрать документацию

Если ок - давайте мержить. Попробуйте кто-нибудь собрать )