Со времени появления первого языка разметки текста, который поддерживает «древопись», прошло вот уже несколько лет, однако достойного текста, демонстрирующего преимущества новой технологии письменности, так и не появилось.
И самым большим «древотекстом» была пара абзацев из документации к пк-разметке {‘Дополнительные возможности форматирования’ → ‘Спойлеры (разворачиваемый блок информации)’ → ‘Для чего нужна последняя форма’ → см. скрытый текст после слова ‘древовидно’}, которые составляют всего ~1300 знаков.
А на английском языке «древотекста» как такового не было вообще [не считая маленькие вставки в документации к языку программирования 11l (например ‘Boolean type’ в Built-in types)].
Но в прошлом году...
… когда я приводил в порядок мета-информацию своих проектов, я заметил, что в итоге я пришёл к записи номеров версий в виде/форме
ГГГГ.М[.н]. После чего мне пришла идея дать имя такому обозначению — YearVer [очевидно, по аналогии с SemVer]. А правило называния дополнительных версий {опубликованных в этом же месяце, либо исправляющих ошибки основной версии} составило основу текста нового сайта.Вскоре со страницы Software versioning в Википедии я узнал про существование CalVer. Это несколько разочаровало меня, но познакомившись поближе, я увидел, что сайт calver.org не даёт никаких конкретных рекомендаций, какую именно схему «календарного версионирования» следует использовать, а просто описывает уже использующиеся схемы в различных проектах, никак не выделяя их.
Таким образом, создание сайта для YearVer осталось актуальным, и я принялся за продолжение его наполнения.
В итоге описание схемы версинирования YearVer получилось достаточно небольшим, лаконичным, но очень определённым, предлагающим конкретные схемы/стратегии в зависимости от типа проекта.
Осталось теперь самое интересное — перевести веб-страницу yearver.org/ru на английский с сохранением форматирования.
Чтобы сделать качественный перевод я решил обратиться сразу в три различных бюро переводов, причём сделав акцент на том, что меня интересует максимальное качество и я готов доплатить за него.
Я обратился в:
- Alconost (был первой ссылкой в результатах поиска в Google по запросу ‘бюро переводов сайтов’)
- transly.ru и tran.su (нашёл поиском по запросу ‘бюро переводов markdown’)
В процессе общения с первым бюро переводов были сформулированы правила чтения «древотекста»:
- Скрытый текст {...} следует раскрывать после прочтения всего [соответствующего] абзаца целиком.
- Скрытый текст {{...}} следует раскрывать после {...}.
Например, в следующем предложении [со страницы http://yearver.org/ru]:Дополнительные версии, опубликованные в этом же месяце, либо {…} исправляющие ошибки основной версии {…}, следует называть
вначале следует раскрыть второй блок скрытого текста (после слов ‘основной версии’), затем все его вложенные блоки, и только потом первый блок (после слова ‘либо’).2021.2.1,2021.2.2и т.д.Почему именно так был составлен этот «древотекст»?(Перед тем как читать это пояснение я настоятельно рекомендую прочесть [в соответствии с данными правилами] указанное предложение со страницы yearver.org/ru целиком)Второй блок скрытого текста (после слов ‘исправляющие ошибки основной версии’) вводит понятие безошибочных проектов, поясняя, что в таких проектах не нужны версии исправляющие ошибки. [И его [второй блок], в общем-то, можно было поместить сразу после слов ‘исправляющие ошибки’ [{но я не стал так делать, т.к. в этом случае первый и второй блоки скрытого текста располагались бы слишком близко друг к другу}].]
А первый блок скрытого текста относится к слову ‘либо’ (поэтому и располагается сразу после него), но, так как в нём используется понятие безошибочных проектов [введённое во втором блоке], раскрывать его следует после второго блока [для чего первый блок и был заключён в дополнительные фигурные скобки].
Теперь перейду к сравнению качества переводов.
Объективно оценить качество перевода достаточно трудно, но косвенным показателем является количество замечаний к переводу. Каждое замечание я оценил по шкале от 1 до 3 баллов [по возрастанию значимости].
\3/
in this case, core version `2021.2.1` might be released in another month
^^^^ (core здесь не нужно, т.к. в исходном тексте говорится
не об основной, а о дополнительной версии [`2021.2.1`])
\3/
If you want to provide a feedback, please submit a ‘GitHub request ’
^^^^^^^^^^^^^^^^^^^
(лучше ‘an issue on GitHub’)
\3/
released to fix bugs in the core version
^^^^^^^^^^^^ (лучше base или main version)
\1/
`N`/`n` is the version number (starting with 1)
^^^^^^^ (лучше sequence)
\2/
each version can be (or must be) without bugfixes
^^^^^^^^ (лучше errors)
\2/
smaller ones, such as command-line tools
^^^^ (в исходном тексте имеется в виду другое)
\1/
those that can be tested by almost 100%
^^^^^^
\1/
However, YearVer can be considered a subset of CalVer.
^^^^^^^ (тут имеется в виду не ‘однако’, а ‘но разумеется’)
\1/
For projects without bugfixes
^^^^^^^^^^^^^^^^^^^^^^^^^ (лучше errorless [или
error-free] projects)
\2/
however, it is supposed that you don't release several new versions within a month
(не соответствует по смыслу оригиналу [‘но рекомендуется выпускать новые версии
не чаще раза в месяц’])
\1/
The key idea behind YearVer
^^^^^^^^ (‘This is not a new or revolutionary idea.’:[https://semver.org/]<)
Итого: 20 баллов.
[Сам перевод можно посмотреть по этой ссылке.]
[[Стоимость перевода: 5637 ₽.]]
\3/
Сломано форматирование:
><'N(1)' Year-based versioning
^^ ^
`2021.2.1` means 'an additional/new
^
'What's wrong with SemVer?' {...}
^ ^^
[а также ещё во многих местах]
\1/
Year-based versioning
^ (должно быть с заглавной буквы, т.к. это заголовок)
\3/
a version that fixes the major version [`2021.2`]
^^^^^ (the major version is `2021`,
here should be ‘main version’)
\1/
Such a strategy is used by [https://www.jetbrains.com/clion/download/other.html] ...
Должно быть:
Such a strategy is used[https://www.jetbrains.com/clion/download/other.html] by ...
\1/
Similarly to par. 2, except for `X`
^^^^ (не уверен, что это подходит тут
[нигде не встречал такого обозначения слова ‘пункт’])
\1/
However, YearVer can, of course, be considered a special
^^^^^^^ (тут имеется в виду не ‘однако’, а ‘но разумеется’)
\3/
If you would like to share your feedback, please submit a 'GitHub Request'
^^^^^^^^^^^^^^^^^^
(лучше ‘an issue on GitHub’)
\1/
The idea of YearVer
^^^^ (‘This is not a new or revolutionary idea.’:[https://semver.org/]<)
\1/
SemVer[https://semver.org/lang/ru/] is a good option for
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (следовало заменить ссылку на
английскую версию этого сайта)
Итого: 15 баллов.
[Несмотря на меньшее количество замечаний, по моему ощущению этот перевод менее качественный, чем от Alconost (слишком дословный, что-ли… больше похоже, что это именно перевод с русского, чем нативный текст на английском).]
[Сам перевод можно посмотреть по этой ссылке.]
[[Стоимость перевода: 4496 ₽.]]
\1/
Year-based versioning
^ (должно быть с заглавной буквы, т.к. это заголовок)
\1/
The idea of YearVer
^^^^ (‘This is not a new or revolutionary idea.’:[https://semver.org/]<)
\1/
choose `2021.2.0` instead of `2021.2`.
^^^^^^ (по моему ощущению слово `choose` не очень подходит)
\3/
the version that fixes the major version [`2021.2`]
^^^^^ (the major version is `2021`,
here should be ‘main version’)
\1/
those fixing bugs in the major version
^^^^^^^^^^^^^
in the same month as the major one
^^^^^
(аналогично, здесь ‘major’ не уместно)
\2/
usually these are small utilities, e.g., command line tools
^^^^ (в исходном тексте имеется в виду другое)
\1/
this strategy is followed by JetBrains [https://www.jetbrains.com/...]
(некорректная ссылка, должно быть например:
this strategy is ‘followed by JetBrains’[https://www.jetbrains.com/...]
)
\1/
'Thus, YearVer (with versions like `YYYY.X` and `YYYY.X.Z`) considers 3 choices'{...}
^ ^
(сломано форматирование [и ещё в паре мест парные кавычки ‘ и ’ заменены на '])
\2/
For bug-fixing projects
^^^^^^^^^^^^^^^^^^^ (не соответствует по смыслу оригиналу)
\1/
Of course, YearVer can be viewed as a special case of CalVer
^ (я бы добавил ‘But’ в начало)
Итого: 14 баллов.
[Сам перевод можно посмотреть по этой ссылке.]
[[Стоимость перевода: 4050 ₽.]]
В заключение [процесса перевода] осталось проделать кропотливую работу по «слиянию» трёх полученных переводов в один текст, выбрав лучшие варианты перевода каждого предложения и каждого термина/понятия.
А классический спойлер — это сам по себе отдельный абзац {но который, также как и блок скрытого текста «древописи», может содержать в себе несколько абзацев}.
| Используя классический спойлер | «Древотекст» |
|---|---|
| Я могу прыгнуть выше Исаакиевского Собора. Вот я прыгнул.
.......
Теперь пусть прыгает Исаакиевский Собор.
|
***
Я могу прыгнуть выше Исаакиевского Собора.
Вот я прыгнул. { Теперь пусть прыгает Исаакиевский Собор.} |
| Эйнштейн умерший попадает в рай. Его принимает Господь, и говорит ему: «тебе что-нибудь хочется узнать у меня, или что-то попросить?» Тот говорит: «Да. Можешь ли ты написать формулу того, как ты всё это сделал?» Бог отвечает: «Могу.» Он [Бог] что-то пишет-пишет.
.......
И вдруг Эйнштейн говорит: «Да подождите! Там же… ошибка!»
Бог [смущённо]:
.......
«Да, я знаю...»
|
***
Эйнштейн умерший попадает в рай.
Его принимает Господь, и говорит ему: «тебе что-нибудь хочется узнать у меня, или что-то попросить?» Тот говорит: «Да. Можешь ли ты написать формулу того, как ты всё это сделал?» Бог отвечает: «Могу.» Он [Бог] что-то пишет-пишет. { И вдруг Эйнштейн говорит: «Да подождите! Там же… ошибка!» Бог [смущённо]: {«Да, я знаю...»}} |
Комментарии (7)
berez
01.02.2022 12:31+2Открыл сайт yearver, посмотрел.
Очень плохо.
Если вкратце: все придуманное удобно для автора, но абсолютно неудобно и бессмысленно для пользователя.
Во-первых, эти ваши деревянные спойлеры сильно мешают воспринимать информацию. Я понимаю, что автору так удобнее: что в голову пришло, то и написал, а потом что показалось лишним — упрятал в удобненький инлайн-спойлер. Но для читателя разбирать такое безобразие — пытка:
— в отличие от обычного спойлера, нет никаких намеков на то, что содержится внутри. У спойлера хотя бы заголовочек бывает, здесь — просто эллипсис {...}. Еще и не выделяющийся на фоне остального текста.
— вложенные «древоспойлеры» лично меня бесят. Наверное, потому, что для читателя «древоспойлеры» очень похожи на сноски в конце книги, т.е. там вроде как дополнительная информация, для получения которой надо открыть книгу в конце и поискать нужную сноску (в нашем случае — навестись мышой на эллипсис и потом заново навестись глазами на поехавший текст). Но когда в тексте сноски идет еще одна сноска — это уже немножко бесяче.
Во-вторых, из-за этих спойлеров информация тупо не видна. Для сайта с документацией это очень-очень странно. Поиск поломан, структуры никакой нет, снаружи на содержимое спойлера никак не сошлешься.
Ожидается, что документация будет построена структурированно, по принципу «сначала кратенько об основном, потом подробненько разбор в деталях, в конце — всякие баги-глюки-закавыки». Да, это требует времени и сил. Зато пользоваться такой документацией удобно, в отличие от неструктурированной кучи скрытых вложенных примечаний.
Теперь собственно о самом YearVer. Схема, опять-таки, удобна для автора (думать не надо), но бессмысленна для пользователя.
Обычная практика версионирования — это major.minor.patch, причем желательно с возможностью легкой сортировки и сравнения. Изменение major части версии обычно означает, что в продукт внесены фичи, несовместимые с предыдущими версиями (например, в библиотеке поменялось ABI, в игре — формат сохранения сейвов и т.п.). По minor и patch частям версии пользователь может прикинуть, какая версия свежее и много ли в ней изменилось (например, если изменился только номер patch, то версии отличаются подфикшенными багами, а если вырос номер minor — ну, небось иконки покрасивше сделали.
У вас же major часть будет меняться каждый год, minor — каждый месяц (или вообще каждый новый билд). Т.е. для пользователя схема версионирования становится максимально непрозрачной: чем отличается 2021.11.1 от 2022.1.1? Получится ли просто обновить версию и работать дальше, или версии обратно несовместимы и придется апгрейдиться по полной?
А еще будут проблемы с сортировкой: лексикографическая сортировка плохо работает с датами без ведущих нулей. Будет примерно такое:
2021.1.1
2021.11.1
2021.12.1
2021.2.1
alextretyak Автор
01.02.2022 14:30Если вкратце: все придуманное удобно для автора, но абсолютно неудобно и бессмысленно для пользователя.
Отвечу также вкратце: это дело привычки.
вложенные «древоспойлеры» лично меня бесят.… Но когда в тексте сноски идет еще одна сноска — это уже немножко бесяче.
Тут отчасти я с вами согласен. Сайт yearver.org в этом отношении является некоторым экспериментом, так как и я обычно стараюсь ограничиваться одним уровнем вложенности (как например тут (см. запись от 2017.11.22 10:03:36) или тут).
Поиск поломан, структуры никакой нет, снаружи на содержимое спойлера никак не сошлешься
Поиск и ссылки на древотекст сделать теоретически возможно (хотя и довольно сложно), но у меня лично при работе с документацией к 11l проблем с этим никогда не возникало.
Ожидается, что документация будет построена структурированно, по принципу «сначала кратенько об основном, потом подробненько разбор в деталях, в конце — всякие баги-глюки-закавыки».
Интересный тезис. А можете привести какой-нибудь реальный пример такой образцовой документации?
Теперь собственно о самом YearVer. Схема, опять-таки, удобна для автора (думать не надо), но бессмысленна для пользователя.
Простите за нескромный вопрос — а вы сами занимались разработкой ПО более или менее профессионально? Тогда разработкой какого ПО, если не секрет? [Я, если что, никакого секрета из своего профессионального опыта не делаю (вкратце он изложен на моей домашней странице).]
в игре — формат сохранения сейвов
Можете привести хоть один пример "увеличения major части версии" в играх? Если появляется вторая часть какой-то игры, то это уже просто другая/новая игра [как правило с полностью несовместимыми сейвами], а не новая версия старой игры. В обновлениях же игр формат хранения сейвов обычно не меняется, а если и меняется, то сейвы всех старых версий всегда поддерживаются в более новых версиях.
Остальные ваши рассуждения в пользу
обычной практики версионированиясемантического версионирования комментировать не вижу смысла, достаточно привести такой факт, что некоторые крупные компании переводят свои проекты с семантического версионирования на календарное (в том числе YearVer), например JetBrains (IntelliJ IDEA, PyCharm, CLion и пр.) и Unity.А на основе моего личного опыта я могу сказать, что календарное версионирование (и в частности YearVer) подходит лучше, чем семантическое, практически для всех проектов, в которых я принимал участие.
delphinpro
01.02.2022 17:36Для прикладного ПО календарное версионирование имеет место быть – можно оценить «свежесть» версии. Если взять тот же JetBrains, то по номеру версии phpStorm 2022.1.1 я вижу, что программа была релизнута в первом квартале 22-го года, т.е. довольно свежая.
Однако для подключаемых библиотек уже не годится, там важнее видеть не «свежесть», а совместимость. Пакеты в npm и packagist использую семантическое версионирование, и номер версии здесь играет большую роль в определении совместимости пакета с вашим окружением разработки.
berez
01.02.2022 19:39А можете привести какой-нибудь реальный пример такой образцовой документации?
Образцовой — нет. А достаточно удобной — да.
Например, Linux Man Pages. Учитывая примитивную технологию, но которой они реализованы — вполне себе хорошечно. Любая страница — это кратенькое описание команды (synopsys), затем более подробный разбор всего и вся (description). И в конце всякое дополнительное знание (caveats, bugs, etc).
Собственно, по тому же образцу построена документация много где. Тот же РНР, например.Простите за нескромный вопрос — а вы сами занимались разработкой ПО более или менее профессионально? Тогда разработкой какого ПО, если не секрет?
Почему занимался? Я и сейчас занимаюсь. Уже двадцать лет всякое пишу — в основном для серверов.А на основе моего личного опыта я могу сказать, что календарное версионирование (и в частности YearVer) подходит лучше, чем семантическое, практически для всех проектов, в которых я принимал участие.
Ключевое слово — «я».
А в проектах, на которых работал я, практически всегда использовалось семантическое версионирование. Причем неспроста — пользователям надо было знать, смогут они обновиться на новую версию малой кровью или придется неделями конфиги править. Но это не значит, что я считаю такое версионирование чем-то особенно полезным.
delphinpro
Почему бы просто не написать нормальный связный текст, вместо всей этой ерунды под названием «древопись»? Это я про сайт. Довольно сложно воспринимается информация, хоть ее там и не много. ИМХО.
novoselov
Максимально неудобная хрень, непонятно где спойлеры, а где ссылки. Текст скачет и нельзя зафиксировать прочитанные блоки, UX на уровне 0.