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

[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 т.ч. не придется сравнивать все файлы.