Improve a bit the documentation

1 files changed, 40 insertions, 32 deletions

diff --git a/doc/source/faq.rst b/doc/source/faq.rst
index 0485f21..df2cdb5 100644
--- a/doc/source/faq.rst
+++ b/doc/source/faq.rst
@@ -54,18 +54,18 @@ Why not Suhosin?
 
 We're huge fans of `Suhosin <https://suhosin.org>`_, unfortunately:
 
-- it doesn't work very well on PHP7
-- it has some oudated features and misses new ones
-- it doesn't cope very well with our various industrialization needs
-- it has some shortcomings by design
+- It doesn't work very well on PHP7+.
+- It has some outdated features and misses modern ones.
+- It doesn't cope very well with some industrialization needs.
+- It has some shortcomings by design.
 
-We're using the `disable_function <https://secure.php.net/manual/en/ini.core.php#ini.disable-functions>`_
-directive, but unfortunately, it doesn't provide enough usable granularity (guess how many CMSs are using
+For example,the `disable_function <https://secure.php.net/manual/en/ini.core.php#ini.disable-functions>`_
+directive doesn't provide enough usable granularity: guess how many CMSs are using
 the `system <https://secure.php.net/manual/en/function.system.php#refsect1-function.system-notes>`_
-function to perform various mandatory maintenance tasks).
+function to perform various mandatory maintenance tasks.
 
 This is why we decided to write our own hardening module, in the spirit of Suhosin,
-with virtual-patching support, as well as other cool new features.
+with virtual-patching support, as well as other fancy new features.
 
 
 What license is Snuffleupagus released under and why?
@@ -75,11 +75,11 @@ Snuffleupagus is licensed under the `LGPL <https://www.gnu.org/copyleft/lesser.h
 was developed by the fine people from `NBS System <https://nbs-system.com/>`__,
 and is maintained by Julien (jvoisin) Voisin.
 
-We chose the LGPL because we don't care that much how you're using Snuffleupagus,
-but we'd like to force people to make their improvements/contributions
-available to everyone.
+The LGPL was chosen because we don't care that much how you're using Snuffleupagus,
+but we'd like to have improvements/contributions made available for everyone to
+benefit from.
 
-The complete license text is shipped with the sources and can be found under ``LICENSE``.
+The complete license text is shipped with the sources and can be found in the ``LICENSE`` file.
 
 For compatibility with older PHP versions, some original PHP source code was copied or ported back to older versions.
 This source code resides in ``src/sp_php_compat.c`` and ``src/sp_php_compat.h`` and retains its original license
@@ -89,12 +89,11 @@ This source code resides in ``src/sp_php_compat.c`` and ``src/sp_php_compat.h``
 What is the different between Snuffleupagus and a (WAF) like ModSecurity?
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-`ModSecurity <https://modsecurity.org/>`__ and other `Web Application
-Firewalls (WAF) <https://en.wikipedia.org/wiki/Web_application_firewall>`__ are
-working by inspecting the http traffic. Snuffleupagus being a PHP module, is
-operating directly inside your website's code, with a lesser overhead, as well
-as a better understanding of what is currently happening inside your
-application.
+`ModSecurity <https://modsecurity.org/>`__ and other `Web Application Firewalls
+(WAF) <https://en.wikipedia.org/wiki/Web_application_firewall>`__ are working
+by inspecting the http traffic. Snuffleupagus being a PHP module, operates
+directly inside the website's code, with a smaller overhead, as well as a
+better comprehension of what is currently happening there.
 
 
 Should I use Snuffleupagus?
@@ -103,18 +102,19 @@ Should I use Snuffleupagus?
 Yes.
 
 Even if you're not using the virtual-patching capabilities, Snuffleupagus comes
-with various passive features that won't break your website while killing numerous vulnerabilities.
+with various passive features that won't break your website while killing
+numerous vulnerability classes.
 
 Please keep in mind that you are not only protecting yourself and your users/customers,
-but also other people on the internet that might be attacked by your server if
-it becomes compromised.
+but also other people on the internet that might be attacked by your server
+should it become compromised.
 
 How mature is this project?
 """""""""""""""""""""""""""
 
-This project has been floating around since early 2016 and we did the first commit
-the 28:sup:`th` of December of the same year. It's currently stable,
-and is usable and used in production.
+This project has been floating around since early 2016 and the first commit
+is from the 28th of December of the same year. It's currently stable,
+and is usable and used in production at various scales.
 
 Are you saying that PHP isn't secure?
 """""""""""""""""""""""""""""""""""""
@@ -137,8 +137,8 @@ all your security issues, but we believe that it might definitely help.
 Sounds great, but is it working?
 """"""""""""""""""""""""""""""""
 
-We've been using it in production since a couple of years, and it thwarted
-numerous known and unknown attacks. If you want some evidences, one of the
+It has been used in production since its inception, and thwarted
+numerous known and unknown attacks. Should you want some evidences, one of the
 developer published in June 2019 a `blogpost
 <https://dustri.org/b/snuffleupagus-versus-recent-high-profile-vulnerabilities.html>`__
 showcasing how efficient Snuffleupagus was versus *major* web
@@ -147,13 +147,13 @@ vulnerabilities from 2018/2019.
 
 Why should I send you bugs, security issues and patches?
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
 Snuffleupagus is an open-source security software, by reporting (or fixing)
 bugs, or implementing new features, you are helping others to protect themselves.
 
-We're also firm believers in the *Beerbounty* system:
-we are happy to offer you beers when/if we ever meet if you helped the project in
-any way. If you don't like beer, we're sure that we'll find something else,
-don't worry.
+We're also firm believers in the *Beerbounty* system: we are happy to offer you
+beers when/if we ever meet if you helped the project in any way. If you don't
+like beer, we're sure that we'll find something else, don't worry.
 
 
 Installation and configuration
@@ -161,6 +161,7 @@ Installation and configuration
 
 Can snuffleupagus break my application?
 """""""""""""""""""""""""""""""""""""""
+
 Yes.
 
 Some options won't break anything, like :ref:`harden-rand <harden-rand-feature>`,
@@ -170,7 +171,7 @@ rules might pretty well break your website.
 It's up to you to configure Snuffleupagus accordingly to your needs.
 
 You can also enable the ``simulation`` mode on features that you're not sure about,
-to see what snuffleupagus would do to your application, before activating them for good.
+to see what Snuffleupagus would do to your application, before activating them for good.
 
 How can I find out the problem when my application breaks?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -180,17 +181,20 @@ By checking the logs; Snuffleupagus systematically prefix them with ``[snuffleup
 
 Does Snuffleupagus run on Windows?
 """"""""""""""""""""""""""""""""""
+
 No idea, feel free to `try <https://github.com/jvoisin/snuffleupagus/issues/2>`_.
 
 
 Does Snuggleupagus run on `HHVM <http://hhvm.com/>`_?
 """""""""""""""""""""""""""""""""""""""""""""""""""""
+
 No it doesn't, since `HHVM's API <https://github.com/facebook/hhvm/wiki/Extension-API>`_
 is really different from PHP7's one. We're not currently planning to rewrite
 Snuffleupagus to support it.
 
 Will Snuffleupagus run on my old PHP 5?
 """""""""""""""""""""""""""""""""""""""
+
 No.
 
 Since PHP5 `is deprecated since the end of 2018 <http://php.net/supported-versions.php>`_,
@@ -202,6 +206,7 @@ Help and support
 
 I found a security issue
 """"""""""""""""""""""""
+
 If you believe you have found a security issue affecting Snuffleupagus,
 then we would be more than happy to hear from you!
 
@@ -219,17 +224,19 @@ you find a security issue.
 
 I found a bug. How can I report it?
 """""""""""""""""""""""""""""""""""
+
 We do have an issue tracker on `Github <https://github.com/jvoisin/snuffleupagus/issues>`_.
 Please make sure to include as much information as possible when reporting your issue,
 such as your operating system, your version of PHP, your version of Snuffleupagus,
 your logs, the problematic PHP code, the request, a brief description, … long story short,
-give us everything that you can.
+give us everything you have.
 
 If you're feeling extra-nice, you can try to :ref:`debug it yourself <debug>`,
 it's not that hard.
 
 Where can I find even more help?
 """"""""""""""""""""""""""""""""
+
 The :doc:`configuration page <config>` might be what you're looking for.
 If you're adventurous, you can also check the `issue tracker <https://github.com/jvoisin/snuffleupagus/issues/?q=is%3Aissue>`_
 (make sure to check the `closed issues <https://github.com/jvoisin/snuffleupagus/issues?q=is%3Aissue+is%3Aclosed>`_ too).
@@ -240,6 +247,7 @@ Unimplemented mitigations and abandoned ideas
 
 Constant time comparisons
 """""""""""""""""""""""""
+
 We didn't manage to perform time-based side-channel attacks on strings 
 against real world PHP application, and the results that we gathered on
 tailored test cases weren't concluding: for simplicity's sake, we chose