Ticket #1742: NewDocHelp

## This is an official page. Only editors and admins can change it.
#acl All:read EditorGroup:read,write
#format rst


Contributing Documentation to TurboGears
========================================

:status: Official

.. contents::
  :depth: 2


|contribute_docs|

.. |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.

.. 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.  
   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``".


Documentation Format & Style Guidelines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In an effort to keep the documentation consistent online and useful offline,
please follow these conventions:


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 Formatting`_ and they also include the 
proper code to include the page comment form.

OfficialTemplate
  For official docs, this template ensures that only editors can edit.

TurboGearsTemplate
  For any contributed or unofficial docs.


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
adding the following code to the top of the page, before any text::

    #format rst

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
status tag::

    This is the Page Title
    ======================

    :Status: Draft

Status tag values should be one or several of "Official", "Contributed",
"Work in Progress", "Draft", "Approved", "Obsolete", "Not verified" etc.

.. _field lists syntax:
    http://docutils.sourceforge.net/docs/user/rst/quickref.html#field-lists


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
headings if you include this markup directly after the status tag::

    .. contents::
        :depth: 2

The ``depth`` option tells the ReST parser how many heading-levels should
be included in the table of contents.



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", etc.)

#. 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
   (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>``
   and the Python package name (e.g. ``wiki_20``) is ``<packagename>``.


ReST Formatting
```````````````

Some markup guidelines and essentials of ReST syntax are listed below. For 
summary reference, visit this `Quick Reference page`_ or this more 
`extensive list`_.

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.


#. 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.

#. 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
   older convention of surrounding literals with quotes, please drop the
   quotes and replace with double backticks.)

#. Block literal sections are for longer examples and command lines.

   If you have a block literal section, and the preceding line ends with a
   colon, just double that colon. For example, instead of inline style
   ``tg-admin info``, you would write::

        Please run::

             tg-admin info

   Please notice the empty line after the double colon and the indentation of
   the literal block (the command).

   With this form there will be one colon at the end of the line preceding the
   literal block in the output. If you don't want this, you can put the double
   colon on a single line and it will not show in the output::

        ::

            foo = Bar()

#. Links should be marked up in the standard ReStructured Text
   `callout style`_::

        This is an `example link`_.

        .. _example link: 1.0/ExampleLink

   * 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_``.

   * 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 
   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 lists have *no* indentation in the ReST source.

#. For ordered lists, don't number the items yourself. Use this syntax instead::

        #. Item one
        #. Item two
        #. ...

#. 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.::
   
        * This is a multi-line
          list item.
        #. List items can have several paragraphs.
        
           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#hyperlink-targets



Document Submission Procedure
-----------------------------

Newly Created Documents
~~~~~~~~~~~~~~~~~~~~~~~

While working on a new document, set the status to *"Work in progress"*.

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


Resources
---------

.. * 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