-
Notifications
You must be signed in to change notification settings - Fork 73
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Улучшение документации #256
Comments
Спрошу здесь, возможно, это начнёт обсуждение. |
@Menelion, спасибо! Часть соглашения была написана, когда уже большой объем текста был переведён, думаю, просто взяли вариант, который чаще встречается 🤔 Если есть более удачный вариант перевода, можно внести изменение в соглашение =) |
Мне тоже кажется, что лучше использовать "часовой пояс", "временная зона" звучит как калька. |
Согласен, давайте тогда заменим :) Предлагаю тогда в новых переводах сразу использовать "часовой пояс", если встретится. Upd: Заодно, может, ещё какие-то варианты улучшим/добавим. |
ОбсуждениеДля подобных исправлений (а также опечаток в оригинале) предложили добавить тег То есть, скорее всего, через какое-то время мы получим рассинхнон в тегах ( Пока добиваем переводы, понаблюдаем за ситуацией, но если рассинхрон появится, думаю, можно будет тогда отступать от оригинала и какие-то вещи улучшать (например, фразы заменять сниппетами |
Если что, у меня где-то валяется php скрипт для поиска устаревшей документации: он рекурсивно обходит все элементы исходного документа( |
Предлагаю после завершения перевода (#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 пустой строкой (если отступа нет, наоборот его необходимо добавить)Комментарии в тексте
Комментарии, не относящиеся к переводу документации необходимо удалить.
Например,
Единообразность терминов
Иногда термины переводятся по-разному, пока не приходит в голову простое решение, как во всей документации поддерживать однообразность, кроме как создания большой вики, но это кажется лишним 😞
Сокращение англицизмов
По возможности, сокращать перевод "this". Например, "this function crops the image", можно перевести, как "функция обрезает изображение", уточнение "эта" будет лишним.
В то же время, там где это местно, можно смело оставлять.
Мелочи
Если в английской версии предложение начинается с маленькой буквы, в русской версии делаем нормально :)
Точки в конце предложения тоже ставим, если они отсутствуют в оригинале.
Используем кавычки-ёлочки, где это уместно.
Персонализация
Не рекомендуется использовать "вы", "мы" и другие местоимения для персонализации, даже если в английской версии персонализированная фраза.
Пример:
НЕПРАВИЛЬНО: "Вы можете использовать второй параметр для ..."
ПРАВИЛЬНО: "Второй параметр используется для..."
Параметры, константы и т.д.
Если в английской версии отсутствует указатель на тип сущности, например,
If <parameter>key</parameter> exists
, предпочтительнее перевести как:Если параметр <parameter>key</parameter> существует
,добавив предполагаемый "параметр".
Блок Return Values
Всегда начинается с "Функция/метод возвращает..."
Чек лист на финальную версию не претендует, все пункты обсждаются =)
The text was updated successfully, but these errors were encountered: