Amend documentation

docs/faq.rst

@@ -5,7 +5,7 @@ FAQ
 
 #. **Can django-environ determine the location of .env file automatically?**
 
-   ``django-environ`` will try to get and read ``.env`` file from the project
+   django-environ will try to get and read ``.env`` file from the project
    root if you haven't specified the path for it when call :meth:`.environ.Env.read_env`.
    However, this is not the recommended way. When it is possible always specify
    the path tho ``.env`` file. Alternatively, you can use a trick with a
@@ -27,5 +27,19 @@ FAQ
 
 #. **Is .env file going to be imported in settings file?**
 
-   No need to import, ``django-environ`` automatically picks variables
+   No need to import, django-environ automatically picks variables
    from there.
+
+#. **Should I commit my .env file?**
+
+   Credentials should only be accessible on the machines that need access to them.
+   Never commit sensitive information to a repository that is not needed by every
+   development machine and server.
+
+#. **Why is it not overriding existing environment variables?**
+
+   By default, django-environ won't overwrite existing environment variables as
+   it assumes the deployment environment has more knowledge about configuration
+   than the application does. To overwrite existing environment variables you can
+   pass ``overwrite=True`` to :meth:`.environ.Env.read_env`. For more see
+   ":ref:`overwriting-existing-env`"

docs/install.rst

@@ -12,7 +12,7 @@ Requirements
 Installing django-environ
 =========================
 
-``django-environ`` is a Python-only package `hosted_on_pypi`_.
+django-environ is a Python-only package `hosted_on_pypi`_.
 The recommended installation method is `pip`_-installing into a
 :mod:`virtualenv <python:venv>`:
 
@@ -22,7 +22,7 @@ The recommended installation method is `pip`_-installing into a
 
 .. note::
 
-   After installing ``django-environ``, no need to add it to ``INSTALLED_APPS``.
+   After installing django-environ, no need to add it to ``INSTALLED_APPS``.
 
 
 .. _hosted_on_pypi: https://pypi.org/project/django-environ/
@@ -43,7 +43,7 @@ experience might be not as smooth:
    # OR
    $ pip install --upgrade https://github.com/joke2k/django-environ.git/archive/develop.tar.gz
 
-This command will download the latest version of ``django-environ`` and install
+This command will download the latest version of django-environ and install
 it to your system.
 
 .. note::

docs/license.rst

@@ -2,7 +2,7 @@
 License and Credits
 ===================
 
-``django-environ`` is open source software licensed under the
+django-environ is open source software licensed under the
 `MIT / X11 License <https://choosealicense.com/licenses/mit/>`_.
 The full license text can be also found in the `source code repository <https://github.com/joke2k/django-environ/blob/main/LICENSE.txt>`_.
 

docs/tips.rst

@@ -55,7 +55,7 @@ See https://perishablepress.com/stop-using-unsafe-characters-in-urls/ for refere
 Smart Casting
 =============
 
-``django-environ`` has a "Smart-casting" enabled by default, if you don't provide a ``cast`` type, it will be detected from ``default`` type.
+django-environ has a "Smart-casting" enabled by default, if you don't provide a ``cast`` type, it will be detected from ``default`` type.
 This could raise side effects (see `#192 <https://github.com/joke2k/django-environ/issues/192>`_).
 To disable it use ``env.smart_cast = False``.
 
@@ -317,6 +317,8 @@ file from the filesystem:
    env.read_env(pathlib.Path(str(BASE_DIR)) / '.env')
 
 
+.. _overwriting-existing-env:
+
 Overwriting existing environment values from env files
 ------------------------------------------------------