Зачем 2 версии (md и wiki) переведенной документации?

[likemusic]

Насколько я понял изначально начали перевод в wiki-формате, а затем уже добавили markdown-версию.

Сейчас получается что (@Butochnikov) и Вы должны отслеживать коммиты друг друга для синхронизации контента в разных папках одного и того же репо. К тому же и тем, кто хочет внести правки в документацию, надо думать в какой папке-версии делать правки (или может сразу в двух).

Может быть стоит с целью упрощения поддержки и развития перевода документации оставить сейчас только markdown версию, как более привычную для github, которая также используется в официальном репо?

[ProgerXP]

Markdown я не переношу на дух, на мой взгляд для работы с большими русскими текстами он никак не подходит. Вики - авторский перевод, как и написано в README. Изменения стоит вносить в wiki, так как именно эта ветка отображается на laravel.ru (об этом написал в README, спасибо). Ветка Markdown была сделана по просьбе @Butochnikov и поддержвается (или не поддерживается) им.

[Butochnikov]

Поддерживаю ProgerXP. Версия Wiki используется на сайте laravel.ru, т.е. это "рабочий" перевод. Все правки прошу вносить в эту версию перевода. Перевод в markdown я делал для тех, кому удобней использовать этот формат. Например, читать сразу в Github. Свою версию я давно не поддерживал, но если у кого есть желание помочь, пожалуйста.

[likemusic]

Markdown я не переношу на дух, на мой взгляд для работы с большими русскими текстами он никак не подходит.

Это чисто субъективное отношение, или есть какие-то объективные причины? Я сам с markdown плотно не работал. Исхожу просто из того, что он используется везде на github, а его создатели наверно выбрали именно его не просто так. Ну и из-за его большей популярности, соответственно будет больше желающих поддержать проект.

[likemusic]

Вообще думаю что в главном репо с переводами должна быть только одна (markdown) версия перевода, а все остальные форматы - должны располагаться в отдельных репо. В этом случае можно сделать хоть в docx, pdf и djvu форматами репо, в readme которых можно указывать id последнего коммита в главном репо c переводом, по которому они актуализированы.

Разные форматы можно собрать в одном общем репо состоящим из подмодулей. Ну и конечно в readme каждого из подмодулей указать ссылку на главный репо с переводом и общее репо с переводами в других форматах.

[Butochnikov]

@likemusic ты готов помогать с переводом? Если да, то напиши мне http://vk.com/butochnikov, обсудим.

[ProgerXP]

Это чисто субъективное отношение, или есть какие-то объективные причины?

Неединообразное форматирование, переключение раскладки при наборе для ввода спецсимволов, примеси HTML, меньше возможностей, встроенных в синтаксис (без использования HTML).

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

[likemusic]

@ProgerXP, судя по Вашим аргументам возможно что действительно тогда лучше оставить в качестве основного репо c wiki, а markdown - как доп формат сделать. Но все равно, как я уже и говорил выше, мне кажется, что разные форматы все-таки должны в разных репо находится, т.к. в этом случае проще отслеживать изменения в главном репо и актуализировать репо с другими форматами.

[likemusic]

@Butochnikov, сейчас markdown создается из UverseWiki скриптом или вручную? Возможно конвертор есть на http://uverse.i-forge.net/, но он сейчас недоступен, поэтому не могу сейчас посмотреть.

[ProgerXP]

сейчас markdown создается из UverseWiki скриптом или вручную?

Вручную, насколкьо я знаю Алексей брал официальные файлы в .md и вносил туда перевод из .wiki. Кропотливая работа. Но я действительно не вижу смысла сейчас переводить всё в md и/или пытаться 100% имитировать официальную структуру документации, так как в конце концов важна сама документация, а не то, что она идентична официальной версии. Какое у тебя мнение на этот счёт?

Возможно конвертор есть на http://uverse.i-forge.net/

Конвертора нет, хотя его, в целом, можно написать. В целом, насколько серьёзные у тебя намерения по вкладу в документацию, с какой целью?

[likemusic]

Какое у тебя мнение на этот счёт?

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

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

[likemusic]

Связался с @Butochnikov через vk, он дал ссылку на https://github.com/LaravelRUS/docs, о которой я не знал. Насколько понял сейчас в нем идет своя независимая от этой версии разработка? Т.е. Вы сейчас сами отслеживаете изменения в нем и правите в wiki-репозитории в соответствии с ним, или нет? Если да, то опять непонятно какой именной ветке в итоге должна соответствовать wiki-версия? Если как вы отвечали ранее - 4.0, тогда вопрос почему не 4.1, как последней стабильной? Если в итоге должно соответствовать 4.1 - то получается что сейчас wiki-репо очень сильно отстает, и если я хочу поддержать wiki-версию, то мне надо коммитить сюда изменения по сравнению с английской веткой 4.1, а сверять с 4.0 бессмысленно, так?

Если https://github.com/LaravelRUS/docs развивается независимо, то возникают еще вопросы. Во-первых, каковы шансы переводу из https://github.com/LaravelRUS/docs появится на laravel.ru вместо того, который есть сейчас основанный на wiki-версии?

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

Если разработка https://github.com/LaravelRUS/docs сейчас действительно идет независимо, то может быть стоит из текущего репо удалить папку c markdown и оставить только wiki-версию, а в readme указать ссылку на независимый репо с markdown?

[Butochnikov]

@likemusic как я уже писал, что wiki документацию надо поддерживать в любом случае, т.к. сейчас это единственная полная версия и ей пользуется все сообщество. "Альтернативный перевод" еще не готов, а когда будет готов, то на сайте будут ссылки сразу на github и, только в том случае, если перевод будет актуальным и будет поддерживаться.

Сейчас, для того чтобы привести wiki документацию к версии 4.1 нужно время. Понимаю, что две версии поддерживать сложно, но такова реальность и каждый делает свой выбор.

[likemusic]

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

[Butochnikov]

я думаю, что такой конвертер будет не сложным.

[ProgerXP]

Связался с @Butochnikov через vk, он дал ссылку на https://github.com/LaravelRUS/docs, о которой я не знал. Насколько понял сейчас в нем идет своя независимая от этой версии разработка?

Я, честно говоря, даже не знал об этом хранилище.

Если как вы отвечали ранее - 4.0, тогда вопрос почему не 4.1, как последней стабильной?

Потому что я переводил документацию в том виде, в каком она была на момент перевода несколько месяцев назад.

Если в итоге должно соответствовать 4.1 - то получается что сейчас wiki-репо очень сильно отстает, и если я хочу поддержать wiki-версию, то мне надо коммитить сюда изменения по сравнению с английской веткой 4.1, а сверять с 4.0 бессмысленно, так?

В моём понимании, и так как это сделано на сайтах вроде jQuery и PHP, гораздо проще иметь одну-единственную версию документации, где в тексте выделяются различия, потому что иначе разработчику, пишущему что-то под разные версии (а это очень вероятно учитывая короткий цикл выпусков Laravel), придётся ходить по разным веткам и выискивать различия и то, как сделать свой код более универсальным.

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

Вообще, зачем так старательно имитировать структуру официального сайта?

Тем кто читает перевод - всегда будет известно насколько он актуальный и какой именно версии соответствует.

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

Сейчас, для того чтобы привести wiki документацию к версии 4.1 нужно время.

А в чём, собственно, проблема? Мы здесь говорим о каких-то сложностях синхронизации с официальной документацией, но по-моему отслеживать изменения и сообщать о них куда проще, чем переводить каждую новую ветку с нуля (особенно текущими темпами выпуски будут чаще, чем релизы документации от сообщества).

Например, предлагаю такой вариант:

1. Находится последний коммит в официальной 4.0, который был на момент, когда было последнее обновление wiki-версии
2. Фиксируется текущий хэш (номер) последнего коммита во всех ветках (4.0, 4.1, dev, будущие) на данный момент и делается полный diff.
3. Зафиксированные номера вписываются в вики-исходники, к примеру в виде {{Meta 4.0=hash, 4.1=hash, dev=hash}}
4. Сделанный diff присылается мне или, если настолько велико желание помочь проекту - выкладывается на форуме, где каждый выбирает фрагмент для обновления. Затем в .wiki вносятся изменения в соответствии с diff всех отслеживаемых версий.
5. Так как базовая версия документации - 4.0, то изменения в 4.0 вносятся в текст как они есть, а изменения будущих версий выносятся под блоками (выносок в тексте) с указанием версии. Аналогично jQuery/PHP/nginx/другим сайтам документации
6. Когда с данной партией diff разобрались - цикл повторяется с пункта 2.

При таком подходе нет никаких проблем с отслеживанием изменений, так как нет нужды вообще сравнивать файлы разных веток документации. Зафиксировали текущую HEAD - сделали diff - внесли правки в wiki. Достаточно описать формат выносок для указания номеров версий в README и проблем с добавлением информации из других веток не будет. Если в ветке появляются новые файлы, которых нет в 4.0, то в файле (заголовке или примечании) указывается номер базовой версии фреймворка, которую описывает этот файл.

я думаю, что такой конвертер будет не сложным.

Конвертор из вики написать легко хотя бы потому, что сам по себе формат вики включает больше возможностей, чем тот же markdown, и он строго описан и не содержит бесконечных подмножеств вроде HTML.

считаю что чем больше репо с различными форматами будет - тем лучше будет для сообщества

С этим я согласен.

[ProgerXP]

Переносим обсуждение на форум.

http://laravel.ru/forum/viewtopic.php?id=288