[doc] Uniformize the introduction for Readme and doc

1 files changed, 32 insertions, 34 deletions

diff --git a/README.rst b/README.rst
index 4da6a750f..d951f7a70 100644
--- a/README.rst
+++ b/README.rst
@@ -1,6 +1,5 @@
-
-README for Pylint - https://pylint.pycqa.org/
-=============================================
+Pylint
+======
 
 .. image:: https://github.com/PyCQA/pylint/actions/workflows/tests.yaml/badge.svg?branch=main
     :target: https://github.com/PyCQA/pylint/actions
@@ -8,7 +7,6 @@ README for Pylint - https://pylint.pycqa.org/
 .. image:: https://coveralls.io/repos/github/PyCQA/pylint/badge.svg?branch=main
     :target: https://coveralls.io/github/PyCQA/pylint?branch=main
 
-
 .. image:: https://img.shields.io/pypi/v/pylint.svg
     :alt: Pypi Package version
     :target: https://pypi.python.org/pypi/pylint
@@ -40,32 +38,44 @@ README for Pylint - https://pylint.pycqa.org/
 
 .. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-pylint?utm_source=pypi-pylint&utm_medium=referral&utm_campaign=readme
 
+Documentation
+=============
 
-======
-Pylint
-======
+Please check `the full documentation`_.
+
+.. _`the full documentation`: https://pylint.pycqa.org/
 
-**It's not just a linter that annoys you!**
+What is pylint ?
+================
 
-Pylint is a Python static code analysis tool which looks for programming errors,
-helps enforcing a coding standard, sniffs for code smells and offers simple refactoring
-suggestions.
+.. Do not modify this without also modifying doc/index.rst
 
-It's highly configurable, having special pragmas to control its errors and warnings
-from within your code, as well as from an extensive configuration file.
-It is also possible to write your own plugins for adding your own checks or for
-extending pylint in one way or another.
+Pylint is a `static code analyser`_ for Python 2 or 3. The latest version supports Python
+3.7.2 and above.
 
-It's a free software distributed under the GNU General Public Licence unless
-otherwise specified.
+.. _`static code analyser`: https://en.wikipedia.org/wiki/Static_code_analysis
 
-Development is hosted on GitHub: https://github.com/PyCQA/pylint/
+Pylint analyses your code without actually running it. It checks for errors, enforces a coding
+standard, looks for `code smells`_, and can make suggestions about how the code could be refactored.
 
-You can use the code-quality@python.org mailing list to discuss about
-Pylint. Subscribe at https://mail.python.org/mailman/listinfo/code-quality/
-or read the archives at https://mail.python.org/pipermail/code-quality/
+.. _`code smells`: https://martinfowler.com/bliki/CodeSmell.html
 
-Pull requests are amazing and most welcome.
+Pylint can infer actual values from your code using its internal code representation (astroid).
+If your code is ``import logging as argparse``, Pylint will know that ``argparse.error(...)``
+is in fact a logging call and not an argparse call.
+
+Pylint isn't smarter than you: it may warn you about things that you have
+conscientiously done or checks for some things that you don't care about.
+During adoption, especially in a legacy project where pylint was never enforced,
+it's best to start with the ``--errors-only`` flag, then disable
+convention and refactor message with ``--disable=C,R`` and progressively
+re-evaluate and re-enable messages as your priorities evolve.
+
+Pylint ships with three additional tools:
+
+- :ref:`pyreverse <pyreverse>` (standalone tool that generates package and class diagrams.)
+- :ref:`symilar <symilar>`  (duplicate code finder that is also integrated in pylint)
+- :ref:`epylint <pylint_in_flymake>` (Emacs and Flymake compatible Pylint)
 
 Install
 -------
@@ -91,18 +101,6 @@ For debian and rpm packages, use your usual tools according to your Linux distri
 More information about installation and available distribution format
 can be found here_.
 
-Documentation
--------------
-
-The documentation lives at https://pylint.pycqa.org/.
-
-Pylint is shipped with following additional commands:
-
-* pyreverse: an UML diagram generator
-* symilar: an independent similarities checker
-* epylint: Emacs and Flymake compatible Pylint
-
-
 Testing
 -------