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

Предлагаю после завершения перевода (#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

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

---

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