Improve documentation for quality checks

Give users more information why the quality check has fired and why it
is important to fix this problem.

Fixes #417

docs/user/checks.rst

@@ -40,28 +40,29 @@ This check ignores some strings which are quite usually same in all languages
 and strips various markup, which can occur in the string, to reduce number of
 false positives.
 
-.. _check-begin-newline:
-
-Starting newline
-~~~~~~~~~~~~~~~~
-
-Source and translated do not both start with a newline.
+This check can help finding strings which were mistakenly not translated .
 
+.. _check-begin-newline:
 .. _check-end-newline:
 
-Trailing newline
-~~~~~~~~~~~~~~~~
+Starting or trailing newline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Source and translated do not both start (or end) with a newline.
 
-Source and translated do not both end with a newline.
+Newlines usually appear in source string for a good reason, so omitting or
+adding it can lead to formatting problems when the translated text is used in
+the application.
 
 .. _check-begin-space:
 
 Starting spaces
 ~~~~~~~~~~~~~~~
 
-Source and translation do not both start with same number of spaces. Space in
-beginning is usually used for indentation in the interface and thus is
-important.
+Source and translation do not both start with same number of spaces. 
+
+Space in beginning is usually used for indentation in the interface and thus
+is important to keep.
 
 .. _check-end-space:
 
@@ -70,6 +71,9 @@ Trailing space
 
 Source and translated do not both end with a space.
 
+Trailing space is usually used to give space between neighbouring elements, so
+removing it might break application layout.
+
 .. _check-end-stop:
 
 Trailing stop
@@ -78,14 +82,22 @@ Trailing stop
 Source and translated do not both end with a full stop. Full stop is also
 checked in various language variants (Chinese, Japanese, Devanagari or Urdu).
 
+Whet the original string is a sentence, the translated one should be sentence
+as well to be consistent within the translated content.
+
 .. _check-end-colon:
 
 Trailing colon
 ~~~~~~~~~~~~~~
 
-Source and translated do not both end with a colon or the colon is not correctly
-spaced. This includes spacing rules for French or Breton. Colon is also
-checked in various language variants (Chinese or Japanese).
+Source and translated do not both end with a colon or the colon is not
+correctly spaced. This includes spacing rules for languages like French or
+Breton. Colon is also checked in various language variants (Chinese or
+Japanese).
+
+Colon is part of a label and should be kept to provide consistent translation.
+Weblate also checks for various typographic conventions for colon, for example
+in some languages it should be preceded with space.
 
 .. _check-end-question:
 
@@ -93,9 +105,14 @@ Trailing question
 ~~~~~~~~~~~~~~~~~
 
 Source and translated do not both end with a question mark or it is not
-correctly spaced. This includes spacing rules for French or Breton. Question
-mark is also checked in various language variants (Armenian, Arabic, Chinese,
-Korean, Japanese, Ethiopic, Vai or Coptic).
+correctly spaced. This includes spacing rules for languages like French or
+Breton. Question mark is also checked in various language variants (Armenian,
+Arabic, Chinese, Korean, Japanese, Ethiopic, Vai or Coptic).
+
+Question mark indicates question and this semantics should be kept in
+translated string as well. Weblate also checks for various typographic
+conventions for question mark, for example in some languages it should be
+preceded with space.
 
 .. _check-end-exclamation:
 
@@ -103,9 +120,14 @@ Trailing exclamation
 ~~~~~~~~~~~~~~~~~~~~
 
 Source and translated do not both end with an exclamation mark or it is not
-correctly spaced. This includes spacing rules for French or Breton.
-Exclamation mark is also checked in various language variants (Chinese,
-Japanese, Korean, Armenian, Limbu, Myanmar or Nko).
+correctly spaced. This includes spacing rules for languages like French or
+Breton.  Exclamation mark is also checked in various language variants
+(Chinese, Japanese, Korean, Armenian, Limbu, Myanmar or Nko).
+
+Exclamation mark indicates some important statement and this semantics should
+be kept in translated string as well. Weblate also checks for various
+typographic conventions for exclamation mark, for example in some languages it
+should be preceded with space.
 
 .. _check-end-ellipsis:
 
@@ -115,43 +137,34 @@ Trailing ellipsis
 Source and translation do not both end with an ellipsis. This only checks for
 real ellipsis (``…``) not for three commas (``...``).
 
+Ellipsis is usually rendered nicer than three commas, so it's good to keep it
+when the original string was using that as well.
+
 .. seealso:: https://en.wikipedia.org/wiki/Ellipsis
 
 .. _check-python-format:
-
-Python format
-~~~~~~~~~~~~~
-
-Python format string does not match source.
-
-.. seealso:: http://docs.python.org/2.7/library/stdtypes.html#string-formatting
-
 .. _check-python-brace-format:
-
-Python brace format
-~~~~~~~~~~~~~~~~~~~
-
-Python brace format string does not match source.
-
-.. seealso:: http://docs.python.org/3.3/library/string.html#string-formatting
-
 .. _check-php-format:
+.. _check-c-format:
 
-PHP format
-~~~~~~~~~~
-
-PHP format string does not match source.
-
-.. seealso:: http://www.php.net/manual/en/function.sprintf.php
+Format strings
+~~~~~~~~~~~~~~
 
-.. _check-c-format:
+Format string does not match source. Weblate supports following formats:
 
-C format
-~~~~~~~~
+* Python format
+* Python brace format
+* PHP format
+* C format
 
-C format string does not match source.
+Omitting format string from translation usually cause severe problems, so you
+should really keep the format string matching the original one.
 
-.. seealso:: https://en.wikipedia.org/wiki/Printf_format_string
+.. seealso::
+    `Python string formatting <http://docs.python.org/2.7/library/stdtypes.html#string-formatting>`_,
+    `Python brace format <http://docs.python.org/3.3/library/string.html#string-formatting>`_,
+    `PHP format strings <http://www.php.net/manual/en/function.sprintf.php>`_,
+    `C printf format <https://en.wikipedia.org/wiki/Printf_format_string>`_
 
 .. _check-plurals:
 
@@ -161,6 +174,9 @@ Missing plurals
 Some plural forms are not translated. Check plural form definition to see for
 which counts each plural form is being used.
 
+Not filling in some plural forms will lead to showing no text in the
+application in case this plural would be displayed.
+
 .. _check-inconsistent:
 
 Inconsistent
@@ -170,29 +186,43 @@ More different translations of one string in a project. This can also lead to
 inconsistencies in displayed checks. You can find other translations of this
 string on :guilabel:`All locations` tab.
 
+Weblate checks translations of the same string across all translation within a
+project to help you keep consistent translations.
+
 .. _check-escaped-newline:
 
 Mismatched \\n
 ~~~~~~~~~~~~~~
 
-Number of \\n in translation does not match source. Usually escaped newlines
-are important for formatting program output, so this should match to source.
+Number of \\n in translation does not match source. 
+
+Usually escaped newlines are important for formatting program output, so this
+should match to source.
     
 .. _check-bbcode:
 
 Mismatched BBcode
 ~~~~~~~~~~~~~~~~~
 
-BBcode in translation does not match source. The method for detecting BBcode is
-currently quite simple.
+BBcode in translation does not match source. 
+
+This code is used as a simple markup to highlight important parts of a
+message, so it is usually a good idea to keep them.
+
+.. note::
+   
+    The method for detecting BBcode is currently quite simple so this check
+    might produce false positives.
 
 .. _check-zero-width-space:
 
 Zero-width space
 ~~~~~~~~~~~~~~~~
 
-Translation contains extra zero-width space (<U+200B>) character. This
-character is usually inserted by mistake.
+Translation contains extra zero-width space (<U+200B>) character. 
+
+This character is usually inserted by mistake, though it might have legitimate
+use. Some programs might have problems when this character is used.
 
 .. seealso:: https://en.wikipedia.org/wiki/Zero-width_space
 
@@ -201,9 +231,10 @@ character is usually inserted by mistake.
 XML tags mismatch
 ~~~~~~~~~~~~~~~~~
 
-XML tags in translation do not match source. This usually means resulting
-output will look different. In most cases this is not desired result from
-translation, but occasionally it is desired.
+XML tags in translation do not match source. 
+
+This usually means resulting output will look different. In most cases this is
+not desired result from translation, but occasionally it is desired.
 
 Source checks
 +++++++++++++
@@ -232,8 +263,10 @@ For example with Gettext in Python it could be:
 Ellipsis
 ~~~~~~~~
 
-The string uses three dots (``...``) instead of an ellipsis character (``…``). Using
-Unicode character is in most cases better approach and looks better.
+The string uses three dots (``...``) instead of an ellipsis character (``…``). 
+
+Using Unicode character is in most cases better approach and looks better when
+rendered.
 
 .. seealso:: https://en.wikipedia.org/wiki/Ellipsis
 
@@ -247,4 +280,5 @@ usually indication that something could be done about improving the source
 string. 
 
 This check can be quite often caused by missing full stop at the end of
-sentence or similar minor issues which translators tend to fix in translations.
+sentence or similar minor issues which translators tend to fix in
+translations, while it would be better to fix it in a source string.