Update for structure

Author: AA-Turner

documentation/help-documenting.rst

@@ -14,10 +14,9 @@ This high-level **Helping with Documentation** section provides:
 * an overview of Python's documentation
 * how to help with documentation issues
 * information on proofreading
-* guidance on contributing to this Developer's Guide
 
-The next chapter, :ref:`Documenting Python <documenting>`, gives extensive,
-detailed information on how to write documentation and submit changes.
+You will find extensive and detailed information on how to write documentation
+and submit changes on the :ref:`Documenting Python <documenting>` page.
 
 
 Python Documentation

documentation/markup.rst

@@ -6,6 +6,9 @@ reStructuredText Markup
 
 .. highlight::  rest
 
+This document describes the custom reStructuredText markup introduced by Sphinx
+to support Python documentation and how it should be used.
+
 
 .. _rst-primer:
 
@@ -190,7 +193,8 @@ A directive is a generic block of explicit markup.  Besides roles, it is one of
 the extension mechanisms of reST, and Sphinx makes heavy use of it.
 
 Basically, a directive consists of a name, arguments, options and content. (Keep
-this terminology in mind, it is used in the next chapter describing custom
+this terminology in mind, it is used in `:ref:`the next section
+<Additional Markup Constructs>` describing custom
 directives.)  Looking at this example,
 
 ::

documentation/start-documenting.rst

@@ -11,10 +11,6 @@ contributed by various authors. The markup used for the Python documentation is
 `reStructuredText`_, developed by the `docutils`_ project, amended by custom
 directives and using a toolset named `Sphinx`_ to post-process the HTML output.
 
-This document describes the style guide for our documentation as well as the
-custom reStructuredText markup introduced by Sphinx to support Python
-documentation and how it should be used.
-
 The documentation in HTML, PDF or EPUB format is generated from text files
 written using the :ref:`reStructuredText format <markup>` and contained in the
 :ref:`CPython Git repository <setup>`.
@@ -43,7 +39,7 @@ The involvement of the community takes many forms, from authoring to bug reports
 to just plain complaining when the documentation could be more complete or
 easier to use.
 
-This document is aimed at authors and potential authors of documentation for
+This section is aimed at authors and potential authors of documentation for
 Python.  More specifically, it is for people contributing to the standard
 documentation and developing additional documents using the same tools as the
 standard documents.  This guide will be less useful for authors using the Python
@@ -56,7 +52,7 @@ documented here, there's a welcoming place for you among the Python contributors
 as well.  Any time you feel that you can clarify existing documentation or
 provide documentation that's missing, the existing documentation team will
 gladly work with you to integrate your text, dealing with the markup for you.
-Please don't let the material in this document stand between the documentation
+Please don't let the material in this section stand between the documentation
 and your desire to help out!
 
 

documentation/style-guide.rst

@@ -6,6 +6,9 @@ Style Guide
 
 .. highlight::  rest
 
+This document describes the style guide for our documentation.
+
+
 Use of whitespace
 =================
 

testing/new-buildbot-worker.rst

@@ -14,7 +14,7 @@ supported by corporations.  Even the corporate sponsored buildbots, however,
 tend to exist because some individual championed them, made them a reality, and
 is committed to maintaining them.
 
-Anyone can contribute a buildbot to the fleet.  This chapter describes how
+Anyone can contribute a buildbot to the fleet.  This document describes how
 to go about setting up a buildbot worker, getting it added, and some hints about
 buildbot maintenance.