diff options
author | Arslan Noor <arslannoorpansota@gmail.com> | 2022-06-30 10:37:54 +0200 |
---|---|---|
committer | Carlton Gibson <carlton@noumenal.es> | 2022-06-30 11:09:06 +0200 |
commit | 5c93a84f44054034f495267ff2400a5de69a4fc1 (patch) | |
tree | 997786365e33cf9ece0e484d292f0a8d748b3d3f /docs/internals/contributing/writing-documentation.txt | |
parent | bb2c5f69f47466fa52f3cf2727d10b3ebd79a4da (diff) | |
download | django-5c93a84f44054034f495267ff2400a5de69a4fc1.tar.gz |
Corrected various typos in contributing docs.
Diffstat (limited to 'docs/internals/contributing/writing-documentation.txt')
-rw-r--r-- | docs/internals/contributing/writing-documentation.txt | 16 |
1 files changed, 8 insertions, 8 deletions
diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 97fc87ac15..5303e61517 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -2,7 +2,7 @@ Writing documentation ===================== -We place a high importance on consistency and readability of documentation. +We place high importance on the consistency and readability of documentation. After all, Django was created in a journalism environment! So we treat our documentation like we treat our code: we aim to improve it as often as possible. @@ -29,7 +29,7 @@ Django release. If you'd like to start contributing to our docs, get the development version of Django from the source code repository (see :ref:`installing-development-version`). The development version has the -latest-and-greatest documentation, just as it has latest-and-greatest code. +latest-and-greatest documentation, just as it has the latest-and-greatest code. We also backport documentation fixes and improvements, at the discretion of the merger, to the last release branch. That's because it's highly advantageous to have the docs for the last release be up-to-date and correct (see @@ -92,7 +92,7 @@ The documentation is organized into several categories: Providing background context helps a newcomer connect the topic to things that they already know. -* :doc:`Reference guides </ref/index>` contain technical reference for APIs. +* :doc:`Reference guides </ref/index>` contain technical references for APIs. They describe the functioning of Django's internal machinery and instruct in its use. @@ -120,7 +120,7 @@ Writing style ============= When using pronouns in reference to a hypothetical person, such as "a user with -a session cookie", gender neutral pronouns (they/their/them) should be used. +a session cookie", gender-neutral pronouns (they/their/them) should be used. Instead of: * he or she... use they. @@ -351,7 +351,7 @@ Documenting new features Our policy for new features is: All documentation of new features should be written in a way that - clearly designates the features are only available in the Django + clearly designates the features that are only available in the Django development version. Assume documentation readers are using the latest release, not the development version. @@ -359,7 +359,7 @@ Our preferred way for marking new features is by prefacing the features' documentation with: "``.. versionadded:: X.Y``", followed by a mandatory blank line and an optional description (indented). -General improvements, or other changes to the APIs that should be emphasized +General improvements or other changes to the APIs that should be emphasized should use the "``.. versionchanged:: X.Y``" directive (with the same format as the ``versionadded`` mentioned above. @@ -461,7 +461,7 @@ example: You can find both in the :doc:`settings reference document </ref/settings>`. - We use the Sphinx :rst:role:`doc` cross reference element when we want to + We use the Sphinx :rst:role:`doc` cross-reference element when we want to link to another document as a whole and the :rst:role:`ref` element when we want to link to an arbitrary location in a document. @@ -531,7 +531,7 @@ Entries that have a status of "broken" need to be fixed. Those that have a status of "redirected" may need to be updated to point to the canonical location, e.g. the scheme has changed ``http://`` → ``https://``. In certain cases, we do not want to update a "redirected" link, e.g. a rewrite to always -point to the latest or stable version of documentation, e.g. ``/en/stable/`` → +point to the latest or stable version of the documentation, e.g. ``/en/stable/`` → ``/en/3.2/``. Translating documentation |