[Python-checkins] devguide: Add an intro task to help with the docs.

Sat Jan 8 21:14:09 CET 2011

brett.cannon pushed c57af2c759cb to devguide:
http://hg.python.org/devguide/rev/c57af2c759cb
changeset: 51:c57af2c759cb
tag: tip
user: Brett Cannon <brett at python.org>
date: Sat Jan 08 12:13:59 2011 -0800
summary:
 Add an intro task to help with the docs.
files:
 docquality.rst
 index.rst

diff --git a/docquality.rst b/docquality.rst
new file mode 100644
--- /dev/null
+++ b/docquality.rst
@@ -0,0 +1,50 @@
+.. _docquality:
+
+Helping with Documentation
+==========================
+
+Python is known for having good documentation. But maintaining all of it and
+keeping a high level of quality takes a lot of effort. Help is always
+appreciated with the documentation, and it requires little programming
+experience (with or without Python).
+
+`Documenting Python`_ covers the details of how Python's documentation works.
+It includes an explanation of the markup used (although you can figure a lot
+out simply by looking at pre-existing documentation) and how to build the
+documentation (which allows you to see how your changes will look along with
+validating your new markup is correct).
+
+.. _Documenting Python: http://docs.python.org/py3k/documenting/index.html
+
+
+Helping with issues filed on the issue tracker
+----------------------------------------------
+
+If you look at `issues assigned to docs at python`_ on the `issue tracker`_, you
+will find various documentation problems that need work. Issues vary from
+typos, to unclear documentation, to something completely lacking documentation.
+
+If you decide to tackle a documentation issue, you simply create a patch for
+the issue and upload it. If you are worried that someone else might be working
+simultaneously on the issue, simply leave a comment on the issue saying you are
+going to try and create a patch and roughly how long you think you will take to
+do it (this allows others to take on the issue if you happen to forget or lose
+interest).
+
+.. _issue tracker: http://bugs.python.org
+.. _issues assigned to docs at python: http://bugs.python.org/issue?%40search_text=&ignore=file%3Acontent&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&components=&versions=&dependencies=&assignee=docs%40python&keywords=&priority=&%40group=priority&status=1&%40columns=status&resolution=&nosy_count=&message_count=&%40pagesize=50&%40startwith=0&%40action=search
+
+
+Proofreading
+------------
+
+While an issue filed on the `issue tracker`_ means there is a known issue
+somewhere, that does not mean there are not other issues lurking about in the
+documentation. Simply proofreading parts of the documentation are enough to
+uncover problems (e.g., documentation that needs to be updated for Python 3
+from Python 2).
+
+If you decide to proofread, then read a section of the documentation from start
+to finish, filing issues in the issue tracker for each problem you find. Don't
+file a single issue for an entire section containing multiple problems as that
+makes it harder to break the work up for multiple people to help with.
diff --git a/index.rst b/index.rst
--- a/index.rst
+++ b/index.rst
@@ -8,6 +8,7 @@
 patch
 runtests
 coverage
+ docquality
 
 
 .. todolist::
@@ -30,7 +31,7 @@
 * :ref:`runtests`
 * Projects to get familiar with the development process
 * :ref:`coverage`
- * `Fixing documentation bugs <XXX>`_
+ * :ref:`docquality`
 * Projects for once you are comfortable
 * `Helping triage issues <XXX>`_
 * `Fixing issues considered "easy" <XXX>`_ (and beyond)
--
Repository URL: http://hg.python.org/devguide
