Ticket #1742: DocHelpRevision.txt

--- OldDocHelp  2008-03-10 20:52:47.000000000 -0700
+++ NewDocHelp  2008-03-10 22:11:26.000000000 -0700
@@ -16,32 +16,63 @@
 
 .. |contribute_docs| image:: 1.0/RoughDocs/contribute_docs.jpg
 
+Three Ways to Help
+------------------
+
 There are three ways to help make and maintain TurboGears documentation:
 
 #. Comment! Pages should all have a comments box at the bottom. Add your
    comments if you see a problem.
 
-#. Add to the RoughDocs section for the version of TurboGears you're using.
-   Anyone can add and edit documentation there. Please do!
+.. Note:: Note: Comment sections have been increasingly locked up due to wiki
+   spamming. Sorry for this inconvenience.
+
+2. `Add to the RoughDocs`_ section for the version of TurboGears you're using.
+   Anyone can add and edit documentation there following the directions below.
+   Please do!
 
 #. Become an editor! Knowledgeable TurboGears users with the interest and
-   aptitude can become editors. Editors are able to edit the "official" docs.
+   aptitude can become editors. Editors are able to edit the "official" docs.  
+   To get involved, visit the `documentation team page 
+   <DocTeam>`_.
+
+
+.. _Add to the RoughDocs:
+
+How to Add or Change Documentation
+----------------------------------
+
+
+Putting Docs in the Right Places
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All docs about the TurboGears framework *must* have a version number at the
+beginning of the page name (i.e the last part of the URL), in sub wiki syntax.
+If you write a page about Apache deployment for TurboGears 1.0, that page
+should be called "``1.0/ApacheDeployment``".
+
+New articles should be linked from the RoughDocs page for the applicable 
+version (e.g. `1.0/RoughDocs <1.0/RoughDocs>`_) until they have been reviewed 
+and approved by the editors and given "official" status. This also ensures that 
+new documents don't get lost and others can benefit from and/or contribute to 
+them immediately.
+
+Multi-page documents should use the sub wiki format to reflect the pages, e.g.
+"``1.0/20MinuteWiki/Page1``".
+
 
-If you're looking to contribute docs in RoughDocs or as an editor, be sure
-to read the following sections and the `documentation team page <DocTeam>`_.
+Documentation Format & Style Guidelines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+In an effort to keep the documentation consistent online and useful offline,
+please follow these conventions:
 
-Documentation Format
---------------------
 
-All documentation should be in ReStructuredText format, not the standard wiki
-markup. This is very important for ensuring the long term value of the docs we
-write. We expect to move to another documentation system at some point in the
-future, or we might want to convert the docs to printable form. The use of
-ReStructuredText will allow us to do that without complex document conversions.
+All documentation should be in *ReStructuredText (ReST)* format, **not the standard wiki
+markup** [#]_.
 
 There are two templates that should be used to get you going with your document.
-Both templates set the format to ReST and they also include the proper code to
+Both templates set the format to `ReST Formatting`_ and they also include the proper code to
 include the page comment form.
 
 OfficialTemplate
@@ -51,8 +82,8 @@
   For any contributed or unofficial docs.
 
 
-ReST Syntax
-~~~~~~~~~~~
+Designating ReST Syntax
+```````````````````````
 
 Please note that if you choose not to use one of these templates you will have
 to explicitly tell MoinMoin that you are using ReST syntax. This is done by
@@ -60,17 +91,11 @@
 
     #format rst
 
-MoinMoin includes a page with a `ReStructuredText primer`_ and also includes
-information on the `use of ReST in MoinMoin`_.
-
-Please also note the addtional notes on proper ReST formatting below.
-
-.. _restructuredtext primer: HelpOnParsers/ReStructuredText/RstPrimer
-.. _use of rest in moinmoin: HelpOnParsers/ReStructuredText
+Proper `ReST formatting`_ syntax is discussed below.
 
 
 Page Status
-~~~~~~~~~~~
+```````````
 
 All documentation pages should display their editorial status right below the
 main heading (like this page does). Use the `field lists syntax`_ for the
@@ -89,7 +114,7 @@
 
 
 Table of Contents
-~~~~~~~~~~~~~~~~~
+`````````````````
 
 All pages with longer than a screen page should have a table of contents.
 This will be generated automatically by the wiki software from the section
@@ -102,84 +127,70 @@
 be included in the table of contents.
 
 
-Putting Docs in the Right Places
---------------------------------
-
-All docs about the TurboGears framework *must* have a version number at the
-beginning of the page name (i.e the last part of the URL), in sub wiki syntax.
-If you write a page about Apache deployment for TurboGears 1.0, that page
-should be called "``1.0/ApacheDeployment``".
-
-New articles should be linked from the `RoughDocs <1.0/RoughDocs>`_ page for the
-proper version as long as they haven't been checked and approved by the editors
-and given an "official" status. This also ensures that new documents don't get
-lost and others can benefit from them and/or contribute.
-
-Multi-page documents should use the sub wiki format to reflect the pages, e.g.
-"``1.0/20MinuteWiki/Page1``".
-
-
-Style Guidelines
-----------------
-
-In an effort to keep the documentation consistent online and useful offline,
-please follow these conventions:
-
 
 Language & Style
-~~~~~~~~~~~~~~~~
+````````````````
 
 #. **Please pay attention to proper spelling, grammar, and style!**
-   For example, all full sentences should end with a full stop, proper names
-   should be capitalized, common word contractions should be written out
-   (i.e. "you should" instead of "you'd") and so on.
-
-#. Avoid too many abbreviations and jargon speak. Not every reader of the
-   docs is an English native speaker!
+   For example, 
 
+ * All full sentences should end with a full stop.
+ * Proper names should be capitalized.
+ * Common word contractions should be written out
+   (i.e. "you should" instead of "you'd", etc.)
+
+2. Avoid too many abbreviations and jargon speak.
+
+#. Avoid slang and idioms (e.g. "This should be a piece of cake.") Not every 
+   reader of the docs is a native English speaker so it will not always 
+   mean what you meant it to mean!
 
 #. All major words in the page title and headings should be capitalized
-   ("This is a Good Heading"). The exceptions are articles, conjunctions,
-   and short prepositions, etc.)
+   (e.g. "This is a Good Heading", but "This is not a good heading".) The 
+   exceptions are articles, conjunctions, and short prepositions, etc.
 
 
 #. Use literal syntax (see below) for names of Python objects, functions,
    modules etc., shell commands, software packages, and so on.
 
-
 #. A full command line should go in a block literal (see below) so that it is
    easier to notice.
 
-#. The name for an example project (e.g. ``Wiki 20`') is ``<projectname>``
+#. The name for an example project (e.g. ``Wiki 20``) is ``<projectname>``
    and the Python package name (e.g. ``wiki_20``) is ``<packagename>``.
 
 
 ReST Formatting
-~~~~~~~~~~~~~~~
+```````````````
 
-#. Please keep the ReST source nicely formatted by wrapping lines at 80
-   characters, inserting two empty lines before and one after each heading
-   and keeping the indentation of literal blocks consistent.
+Some markup guidelines and essentials of ReST syntax are listed below. For 
+summary reference, visit this `Quick Reference page`_ or this more 
+`extensive list`_.
 
-   In short, treat the ReST source as you would treat Python source code.
-   You want this to be beautiful as well, don't you?
+Treat the ReST source as you would treat Python source code by making it
+nicely formatted and beautiful. When it helps, you can edit the page source 
+in your local editor and paste it back into the wiki editor interface when 
+you ready.
 
-   You can edit the page in your local editor and paste it back to the
-   wiki editor interface when you ready.
 
+#. Wrap ReST source lines at 80 characters.
+
+#. Insert two empty lines before and one after each heading.
+
+#. Keep the indentation of literal blocks consistent.
 
 #. The page title should be underlined with equal signs (``=``).
 
 #. Section headings should be underlined with ``-`` (dash), ``~`` (tilde),
    and ` (backtick), according to their level in the section hierarchy in
    the order given here. Keep the underline the same length as the section
-   title (you can do this in the final proof-reading phase).
+   title.
 
-#. Literals are any chunk of code (including variable names and parameters)
+#. Literals are any chunk of code, including variable names and parameters
    and anything you type directly into a terminal. Literals are surrounded
-   by double backticks. If you run across one of the few instances of the
+   by double backticks. (If you run across one of the few instances of the
    older convention of surrounding literals with quotes, please drop the
-   quotes and replace with double backticks.
+   quotes and replace with double backticks.)
 
 #. Block literal sections are for longer examples and command lines.
 
@@ -209,27 +220,29 @@
 
         .. _example link: 1.0/ExampleLink
 
-   If the URL is very long, you can put a line break behind the colon and indent
-   the URL on the next line. Put the all URLs from one section at the end of
+ * If the URL is very long, you can put a line break after the colon and indent
+   the URL on the next line.
+
+ * Put the all URLs from one section at the end of
    the section.
 
-   One-word links don't need backticks: ``mylink_``.
+ * One-word links don't need backticks: ``mylink_``.
 
-   The link target should not be enclosed in backticks and case does not matter.
+ * The link target should not be enclosed in backticks and is not case-sensitive.
 
-#. Try to use list syntax for lists instead of formatting the lists yourself by
-   using bold text or italicized text. This mostly comes up when dealing with
-   lists of arguments etc., check the `Configuration <1.0/Configuration>`_ page
-   for an example::
+9. Try to use list syntax for lists instead of formatting the lists yourself 
+   with bold or italics. This mostly comes up when dealing with lists of 
+   arguments etc. The `Configuration <1.0/Configuration>`_ page is a good
+   example::
 
     ``arg1``
        argument 1 explanation text
     ``arg2``
        argument 2 explanation text
 
-#. First-level list have *no* indentation in the ReST source.
+#. First-level lists have *no* indentation in the ReST source.
 
-#. For ordered lists, don't number the items yourself, use this syntax instead::
+#. For ordered lists, don't number the items yourself. Use this syntax instead::
 
         #. Item one
         #. Item two
@@ -238,6 +251,7 @@
 #. You can also break lines in lists, footnotes and notes, if you indent the 
    second and following lines the same level.
    
+
    For list items, the indentation level must match that of the first letter on 
    the first line, e.g.::
    
@@ -247,37 +261,113 @@
         
            Like this.
 
+
+Remember, pages marked with "Official[, Approved]" are considered to be
+accurate, reviewed and have proper style. Copy editing is an essential
+part of maintaining high quality documents.
+
 .. _callout style:
-     http://docutils.sourceforge.net/docs/user/rst/quickref.html#contents
+    http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-targets
 
 
-Editor Guidelines
------------------
 
-If you bless a page by marking it as official, please send a note to
-turbogears-docs saying so. We, the DocTeam_, would like to keep track
-of things without missing them in the noise of RecentChanges_ and I'm
-sure you would as well.
+Document Submission Procedure
+-----------------------------
 
-If you work on a document that is marked official, please
+Newly Created Documents
+~~~~~~~~~~~~~~~~~~~~~~~
 
-#. Take extra care.
+While working on a new document, set the status to *"Work in progress"*.
 
-#. Set the status to "Official, Work in progress" while you are working
-   on it and to "Official, Draft" until at least one other person had a
-   chance to look at your changes.
+Once completed to your satisfaction,
+
+#. Change status to *"Draft"*.
+
+#. Open a new Trac ticket requesting a review. (See `Opening New Document Tickets`_
+   below.)
+
+
+
+Improvements upon Existing Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Editable Documents
+``````````````````
+* If you think you know what you are doing:
+
+ #. Edit document directly.
+ #. Do not open a ticket.
+
+* If you have doubts:
+
+ #. Edit what you can.
+ #. Open *one* ticket for review and all the rest of the issues with that page
+
+Official Documents
+``````````````````
+
+If you work on a document that is marked *Official*,
+
+* If you have write access:
+
+ #. Please take extra care.
+
+ #. Set the status to "Official, Draft" until at least one other person has
+    had a chance to look at your changes.
+
+ #. Open a new ticket.
+
+* If you do not have write access:
+
+ #. Download raw text of the original document.
+ #. Make changes at your local computer.
+ #. Create a diff file of your changes with `diff -u old new`.
+ #. Open a new ticket.
+ #. Attach diff file to ticket.
+
+
+Opening New Document Tickets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#. Open a `new Trac ticket`_.
+
+#. Put the document's title in the ticket summary
+
+#. Set Component=Docs
+
+#. Set Version=X.0 (one decimal place only)
+
+#. Set Keywords to "doc review"
+
+#. If you could not edit the document yourself, attach a diff file
+   of your proposed changes.
+
+.. _new Trac ticket: http://trac.turbogears.org/newticket
 
-Remember, pages marked with "Official[, Approved]" are considered to be
-accurate, reviewed and have proper style. Copy editing is an essential
-part of maintaining high quality documents.
 
 Resources
 ---------
 
-* There are some wiki ReST syntax snippets ready to be copied and pasted
-  on Chris Arndt's `personal wiki page`_
-* There is a list with further resources for documentation writers on the
-  `documentation team page`_.
+.. * There are some wiki ReST syntax snippets ready to be copied and pasted
+   on Chris Arndt's `personal wiki page`_
+
+* `Documentation Team Page`_
+* `ReST Quick Reference`_
+* Lots of `ReST Information`_
+* `RoughDocs Page for 1.0 <1.0/RoughDocs>`_
+* `TurboGears Trac <http://trac.turbogears.org>`_
 
 .. _personal wiki page: ChristopherArndt/Snippets 
 
+
+.. [#] This is very important for ensuring the long term value of the
+       docs we write. We expect to move to another documentation system 
+       at some point in the future, or we might want to convert the docs to
+       printable form. The use of ReStructuredText will allow us to do 
+       that without complex document conversions.
+
+.. _ReST Information:
+.. _extensive list: http://docutils.sourceforge.net/rst.html
+.. _quick reference page:
+.. _ReST Quick Reference:
+    http://docutils.sourceforge.net/docs/user/rst/quickref.html
+