Улучшение документации

[saundefined]

Предлагаю после завершения перевода (#113) заняться улучшением документации.

У файлов есть тег Reviewed, хотя есть вопросы к его актуальности (у части файлов он помечен yes, но без указания проверяющего — такие предлагаю перевести в статус no).
Необходимо проверить все файлы с Reviewed: no, а в идеале, ещё и с Reviewed: yes перепроверить.

Чек лист

Соответствие тегов и их значений

Количество тегов (<literal>, <varname>, ∫, <type>string</type> и т.д.) должно соответствовать английской версии.

Заголовки функций

Заголовок функции refpurpose должен быть в 3 лице, единственном числе и отвечать на вопрос "Что функция делает?", если это допустимо.
Пример — "Пропорционально изменяет размер изображения".
Точка в заголовке не ставится.

Комментарии в коде

Комментарии в коде должны быть переведены.
Комментарии в коде, объясняющие действие, должны быть написаны в форме глагольного существительного, где это уместно.
Пример — "выполнение запроса" (а не "выполнить запрос", "выполняем запрос" и т.д.)

Заголовки примеров

Если в английской версии заголовок примера вместо function() example, например, просто function() ,
в русской версии заголовок должен всё равно быть Пример использования function().

Правильное написание терминов и слов

Если в английской версии используется mysql или blob, в русской версии всё равно используем MySQL и BLOB, соответственно.

Лишние пустые строки и отступы

Лишние пустые строки и отступы удаляются, refsect-блоки разделяются 1 пустой строкой (если отступа нет, наоборот его необходимо добавить)

Комментарии в тексте

Комментарии, не относящиеся к переводу документации необходимо удалить.
Например,

<!-- TODO: we don't need further details here, but this still has to be
       added to the operator precedence table -->
<!-- TODO Drop mention of crypt? -->

Единообразность терминов

Иногда термины переводятся по-разному, пока не приходит в голову простое решение, как во всей документации поддерживать однообразность, кроме как создания большой вики, но это кажется лишним 😞

Сокращение англицизмов

По возможности, сокращать перевод "this". Например, "this function crops the image", можно перевести, как "функция обрезает изображение", уточнение "эта" будет лишним.
В то же время, там где это местно, можно смело оставлять.

Мелочи

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

Персонализация

Не рекомендуется использовать "вы", "мы" и другие местоимения для персонализации, даже если в английской версии персонализированная фраза.

Пример:
НЕПРАВИЛЬНО: "Вы можете использовать второй параметр для ..."
ПРАВИЛЬНО: "Второй параметр используется для..."

Параметры, константы и т.д.

Если в английской версии отсутствует указатель на тип сущности, например,
If <parameter>key</parameter> exists, предпочтительнее перевести как:
Если параметр <parameter>key</parameter> существует,
добавив предполагаемый "параметр".

Блок Return Values

Всегда начинается с "Функция/метод возвращает..."

---

Чек лист на финальную версию не претендует, все пункты обсждаются =)

[Menelion]

Спрошу здесь, возможно, это начнёт обсуждение.
В глоссарии соответствий time zone предлагается переводить как «временная зона», в то время как общепринятый перевод — «часовой пояс». Есть какие-то причины этого выбора? Спрашиваю, поскольку, во-первых, много лет проработал в локализации :), а во-вторых, человек или люди, которые составляли этот глоссарий, кажутся мне опытными профессионалами, ибо больше вопросов у меня (обычно страшно привередливого и, чего греха таить, любящего отстаивать свою точку зрения) вообще не возникло.
Спасибо!

[saundefined]

@Menelion, спасибо!

Часть соглашения была написана, когда уже большой объем текста был переведён, думаю, просто взяли вариант, который чаще встречается 🤔

---

Если есть более удачный вариант перевода, можно внести изменение в соглашение =)

[zors1]

Мне тоже кажется, что лучше использовать "часовой пояс", "временная зона" звучит как калька.

[saundefined]

Согласен, давайте тогда заменим :)

Предлагаю тогда в новых переводах сразу использовать "часовой пояс", если встретится.
А в существующих переводах заменим на этапе вычитки.

Upd: Заодно, может, ещё какие-то варианты улучшим/добавим.

[saundefined]

Обсуждение

Для подобных исправлений (а также опечаток в оригинале) предложили добавить тег [skip-revcheck] в теле коммита.

То есть, скорее всего, через какое-то время мы получим рассинхнон в тегах (&return.falseforfailure;, &null; и т.д.)
за совпадением которых мы сейчас следим.

Пока добиваем переводы, понаблюдаем за ситуацией, но если рассинхрон появится, думаю, можно будет тогда отступать от оригинала и какие-то вещи улучшать (например, фразы заменять сниппетами &return.*) 🤔

[WinterSilence]

Количество тегов (<literal>, <varname>, ∫, <type>string</type> и т.д.) должно соответствовать английской версии.

Если что, у меня где-то валяется php скрипт для поиска устаревшей документации: он рекурсивно обходит все элементы исходного документа(DOMElement::$childNodes) и сравнивает с переводом по имени(DOMElement::$tagName), добавляя отсутствующие элементы.
Если что пишите, попробую найти и скинуть.
Хотя логичнее было бы добавить действие/задачу в workflow php/doc-en которая бы срабатывала при изменении репозитория и обновляла сразу все переводы. Список измененных файлов можно взять из последнего влитого PR т.ч. не придется сравнивать все файлы.

[lex111]

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

Изначально наткнулся на https://www.php.net/manual/ru/migration84.new-features.php, сначала подумал, что это такой черновой вариант, но потом посмотрев остальные страницы доки, разочаровался ещё сильнее, и просто приведу примеры из рандомных коммитов:

В частности на migration84.new-features.php, но относится также и к другим страницам:

• Обильное использования страдательного залога (типа Операциям чтения и записи свойств объектов теперь разрешили добавлять логику поведения почему просто не Операции чтения и записи свойств объектов теперь могут включать логику поведения)
• Персонализация повсюду (Добавили режим округления)
• Дублирующие конструкции вроде который дополнил режим который появился прежде или Добавили константу ..., которую прежде добавили или последовательности символов ?? как последовательности

Как я вижу @mmalferov ежедневно пытается привести документацию к литературной норме, когда это вообще не нужно и никак её не существенно улучшает. Мне в целом непонятно, зачем делать такие обильные стилистические правки, добавляя ещё от себя то, чего нет в оригинале. У данного перевода документации есть устоявшийся стиль, которому логично следовать при новых изменений, иначе получается странная мешанина.

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

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

В частности, к примеру https://www.php.net/manual/ru/function.array-merge.php

Функция возвращает результирующий массив. Без аргументов функция возвращает пустой массив

Зачем тут указывать, что и так понятно, причем дважды

Пример слияния массивов функцией array_merge()

Функция что-то ещё умеет делать, кроме слияния (merge) массивов (array)?!

Пример про расхождение с оригиналом:

Оригинал остался прежним, в переводе теперь что-то своё, очень сомнительное и нужное. Сюда же и относятся стиль форматирования кода, если в оригинале осталось также, смысл менять сам код в переводе?

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

Вот ещё пример изменения, которое изменяет то, что не нужно:

Вместо прижившегося уже перевода зачем-то придуман новый, больше похожий на дословный, взятый в кавычки, вдобавок ко всему приводится оригинальное словосочетание с совершенно ненужной приставкой "англ". И стало разве лучше?!

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

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

В оригинале предложение так же разделено на две строки, смысл менять?

Опять же в названии нет слово про модуль, просто понятное и емкое "фильтрация данных", тогда зачем это лишнее усложнение...

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

---

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

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

Не хочу обесценить ничьих усилий, но как и в любом легаси-проекте нужно осторожно и аккуратно вносить изменения. Немного рефакторить, а не переделывать то, что было исторически накоплено за долгие годы. В данном случае, the damage is done, увы. Я разумеется не могу никак что-то запретить, это всё больше про хорошие практики, но, пожалуйста, перестаньте делать подобные вредительские правки. Очень хотелось, чтобы текущие мейнтейнеры поддерживали документацию в том состоянии, которая она много лет была...

[WinterSilence]

В данном слушае соглашусь с @lex111 - изменения вторичны, но не меняют контекст