From 4a19533ba5f65f839b6bd0fe307a053049230796 Mon Sep 17 00:00:00 2001
From: Daniele Procida <daniele@vurt.org>
Date: Wed, 10 Mar 2021 18:27:30 +0000
Subject: [PATCH 1/2] Renamed Install to Getting started; moved notes to index

---
 doc/en/_templates/globaltoc.html |  2 +-
 doc/en/getting-started.rst       | 18 +++++-------------
 doc/en/index.rst                 | 17 +++++++++++++----
 3 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/doc/en/_templates/globaltoc.html b/doc/en/_templates/globaltoc.html
index 5fc1ea13e..25666d8db 100644
--- a/doc/en/_templates/globaltoc.html
+++ b/doc/en/_templates/globaltoc.html
@@ -2,7 +2,7 @@
 
 <ul>
   <li><a href="{{ pathto('index') }}">Home</a></li>
-  <li><a href="{{ pathto('getting-started') }}">Install</a></li>
+  <li><a href="{{ pathto('getting-started') }}">Get started</a></li>
   <li><a href="{{ pathto('contents') }}">Contents</a></li>
   <li><a href="{{ pathto('reference') }}">API Reference</a></li>
   <li><a href="{{ pathto('example/index') }}">Examples</a></li>
diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst
index 28fd862cf..fad682554 100644
--- a/doc/en/getting-started.rst
+++ b/doc/en/getting-started.rst
@@ -1,22 +1,14 @@
-Installation and Getting Started
+Get Started
 ===================================
 
-**Pythons**: Python 3.6, 3.7, 3.8, 3.9, PyPy3
-
-**Platforms**: Linux and Windows
-
-**PyPI package name**: `pytest <https://pypi.org/project/pytest/>`_
-
-**Documentation as PDF**: `download latest <https://media.readthedocs.org/pdf/pytest/latest/pytest.pdf>`_
-
-``pytest`` is a framework that makes building simple and scalable tests easy. Tests are expressive and readable—no boilerplate code required. Get started in minutes with a small unit test or complex functional test for your application or library.
-
 .. _`getstarted`:
 .. _`installation`:
 
 Install ``pytest``
 ----------------------------------------
 
+``pytest`` requires: Python 3.6, 3.7, 3.8, 3.9, or PyPy3.
+
 1. Run the following command in your command line:
 
 .. code-block:: bash
@@ -35,7 +27,7 @@ Install ``pytest``
 Create your first test
 ----------------------------------------------------------
 
-Create a simple test function with just four lines of code:
+Create a new file called ``test_sample.py``, containing a function, and a test:
 
 .. code-block:: python
 
@@ -47,7 +39,7 @@ Create a simple test function with just four lines of code:
     def test_answer():
         assert func(3) == 5
 
-That’s it. You can now execute the test function:
+The test
 
 .. code-block:: pytest
 
diff --git a/doc/en/index.rst b/doc/en/index.rst
index cfe3a271e..5060d9720 100644
--- a/doc/en/index.rst
+++ b/doc/en/index.rst
@@ -13,10 +13,19 @@ pytest: helps you write better programs
 
 .. module:: pytest
 
-The ``pytest`` framework makes it easy to write small tests, yet
-scales to support complex functional testing for applications and libraries.
+The ``pytest`` framework makes it easy to write small, readable tests, and can
+scale to support complex functional testing for applications and libraries.
 
-An example of a simple test:
+
+**Pythons**: ``pytest`` requires: Python 3.6, 3.7, 3.8, 3.9, or PyPy3.
+
+**PyPI package name**: `pytest <https://pypi.org/project/pytest/>`_
+
+**Documentation as PDF**: `download latest <https://media.readthedocs.org/pdf/pytest/latest/pytest.pdf>`_
+
+
+A quick example
+---------------
 
 .. code-block:: python
 
@@ -56,7 +65,7 @@ To execute it:
     ============================ 1 failed in 0.12s =============================
 
 Due to ``pytest``'s detailed assertion introspection, only plain ``assert`` statements are used.
-See :ref:`Getting Started <getstarted>` for more examples.
+See :ref:`Get started <getstarted>` for a basic introduction to using pytest.
 
 
 Features

From d2d975d6cf916c3f0802341e202869157e82022a Mon Sep 17 00:00:00 2001
From: Daniele Procida <daniele@vurt.org>
Date: Wed, 10 Mar 2021 19:18:21 +0000
Subject: [PATCH 2/2] Reworded titles of some clear how-to guides

Files retitled:

assert.rst
bash-completion.rst
capture.rst
existingtestsuite.rst
mark.rst
monkeypatch.rst
nose.rst
parametrize.rst
plugins.rst
skipping.rst
tmpdir.rst
usage.rst
---
 doc/en/assert.rst            | 2 +-
 doc/en/bash-completion.rst   | 4 ++--
 doc/en/capture.rst           | 2 +-
 doc/en/existingtestsuite.rst | 4 ++--
 doc/en/mark.rst              | 4 ++--
 doc/en/monkeypatch.rst       | 2 +-
 doc/en/nose.rst              | 2 +-
 doc/en/parametrize.rst       | 2 +-
 doc/en/plugins.rst           | 4 ++--
 doc/en/skipping.rst          | 4 ++--
 doc/en/tmpdir.rst            | 4 ++--
 doc/en/usage.rst             | 2 +-
 12 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/doc/en/assert.rst b/doc/en/assert.rst
index e6a23bcf3..c0314f344 100644
--- a/doc/en/assert.rst
+++ b/doc/en/assert.rst
@@ -1,5 +1,5 @@
 
-The writing and reporting of assertions in tests
+How to write and report assertions in tests
 ==================================================
 
 .. _`assertfeedback`:
diff --git a/doc/en/bash-completion.rst b/doc/en/bash-completion.rst
index eaa078814..245dfd6d9 100644
--- a/doc/en/bash-completion.rst
+++ b/doc/en/bash-completion.rst
@@ -1,8 +1,8 @@
 
 .. _bash_completion:
 
-Setting up bash completion
-==========================
+How to set up bash completion
+=============================
 
 When using bash as your shell, ``pytest`` can use argcomplete
 (https://argcomplete.readthedocs.io/) for auto-completion.
diff --git a/doc/en/capture.rst b/doc/en/capture.rst
index caaebdf81..ea0063853 100644
--- a/doc/en/capture.rst
+++ b/doc/en/capture.rst
@@ -1,7 +1,7 @@
 
 .. _`captures`:
 
-Capturing of the stdout/stderr output
+How to capture stdout/stderr output
 =========================================================
 
 Default stdout/stderr/stdin capturing behaviour
diff --git a/doc/en/existingtestsuite.rst b/doc/en/existingtestsuite.rst
index 1e3e192bf..9909e7d11 100644
--- a/doc/en/existingtestsuite.rst
+++ b/doc/en/existingtestsuite.rst
@@ -1,7 +1,7 @@
 .. _existingtestsuite:
 
-Using pytest with an existing test suite
-===========================================
+How to use pytest with an existing test suite
+==============================================
 
 Pytest can be used with most existing test suites, but its
 behavior differs from other test runners such as :ref:`nose <noseintegration>` or
diff --git a/doc/en/mark.rst b/doc/en/mark.rst
index 7370342a9..33f9d18bf 100644
--- a/doc/en/mark.rst
+++ b/doc/en/mark.rst
@@ -1,7 +1,7 @@
 .. _mark:
 
-Marking test functions with attributes
-======================================
+How to mark test functions with attributes
+===========================================
 
 By using the ``pytest.mark`` helper you can easily set
 metadata on your test functions. You can find the full list of builtin markers
diff --git a/doc/en/monkeypatch.rst b/doc/en/monkeypatch.rst
index 4964ee548..d3c7689e4 100644
--- a/doc/en/monkeypatch.rst
+++ b/doc/en/monkeypatch.rst
@@ -1,5 +1,5 @@
 
-Monkeypatching/mocking modules and environments
+How to monkeypatch/mock modules and environments
 ================================================================
 
 .. currentmodule:: _pytest.monkeypatch
diff --git a/doc/en/nose.rst b/doc/en/nose.rst
index e16d76469..486b3db75 100644
--- a/doc/en/nose.rst
+++ b/doc/en/nose.rst
@@ -1,6 +1,6 @@
 .. _`noseintegration`:
 
-Running tests written for nose
+How to run tests written for nose
 =======================================
 
 ``pytest`` has basic support for running tests written for nose_.
diff --git a/doc/en/parametrize.rst b/doc/en/parametrize.rst
index 9e531ddd4..7f5f6ea0c 100644
--- a/doc/en/parametrize.rst
+++ b/doc/en/parametrize.rst
@@ -6,7 +6,7 @@
 
 .. _`parametrize-basics`:
 
-Parametrizing fixtures and test functions
+How to parametrize fixtures and test functions
 ==========================================================================
 
 pytest enables test parametrization at several levels:
diff --git a/doc/en/plugins.rst b/doc/en/plugins.rst
index 8090e7d18..ade51abad 100644
--- a/doc/en/plugins.rst
+++ b/doc/en/plugins.rst
@@ -2,8 +2,8 @@
 .. _`extplugins`:
 .. _`using plugins`:
 
-Installing and Using plugins
-============================
+How to install and use plugins
+===============================
 
 This section talks about installing and using third party plugins.
 For writing your own plugins, please refer to :ref:`writing-plugins`.
diff --git a/doc/en/skipping.rst b/doc/en/skipping.rst
index 610d3d43b..66db74a1f 100644
--- a/doc/en/skipping.rst
+++ b/doc/en/skipping.rst
@@ -2,8 +2,8 @@
 
 .. _skipping:
 
-Skip and xfail: dealing with tests that cannot succeed
-======================================================
+How to use skip and xfail to deal with tests that cannot succeed
+=================================================================
 
 You can mark test functions that cannot be run on certain platforms
 or that you expect to fail so pytest can deal with them accordingly and
diff --git a/doc/en/tmpdir.rst b/doc/en/tmpdir.rst
index adcba02cb..379c6d84c 100644
--- a/doc/en/tmpdir.rst
+++ b/doc/en/tmpdir.rst
@@ -2,8 +2,8 @@
 .. _`tmpdir handling`:
 .. _tmpdir:
 
-Temporary directories and files
-================================================
+How to use temporary directories and files in tests
+===================================================
 
 The ``tmp_path`` fixture
 ------------------------
diff --git a/doc/en/usage.rst b/doc/en/usage.rst
index 0a26182d4..32af9fbeb 100644
--- a/doc/en/usage.rst
+++ b/doc/en/usage.rst
@@ -1,7 +1,7 @@
 
 .. _usage:
 
-Usage and Invocations
+How to invoke pytest
 ==========================================