Rendering of reStructured text is not possible, please install Docutils.

Contributing Docs to TurboGears

:status: Official

.. contents::
  :depth: 2


.. |contribute_docs| image:: 1.0/RoughDocs/contribute_docs.jpg

There are three ways to help make and maintain TurboGears documentation:

1. Comment! Pages should all have a comments box at the bottom. Add your comments if you see a problem.
2. Add to the RoughDocs section for the version of TurboGears you're using. Anyone can add and edit documentation there. Please do!
3. Become an editor! Knowledgeable TurboGears users with the interest and aptitude can become editors. Editors are able to edit the "official" docs.

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

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 Docudo at some point in the future, and the use of ReStructuredText will allow us to do that without complex document conversions.

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 include the page comment form.

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

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

    #format rst

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 main heading

    :Status: Draft

Possible status tag values could be "Official", "Unofficial", "Draft", "Experimental", "Outdated", "Obsolete" etc.

.. _field lists syntax:

MoinMoin includes a `page with a ReStructuredText primer <HelpOnParsers/ReStructuredText/RstPrimer>`_ and also includes information on the `use of ReST in MoinMoin <HelpOnParsers/ReStructuredText>`_.

Putting Docs in the Right Places

All docs about the TurboGears framework *must* have a version number at the beginning of the page name, 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:

1. Titles are underlined only, the order is =, -, ~, ` (backtick)
2. 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.
3. A full command line should go in a block literal so that they're easier to notice. Instead of ``tg-admin info``, you'd write::

    tg-admin info

4. The name for the example package (e.g. Wiki 20) is ``*packagename*`` and the python name is ``*appname*`` (e.g. ``wiki_20``).
5. Try to keep lines wrapped at 80 characters
6. The preferred link syntax is the standard ReStructured Text callout style::

    This is an `example link`_.

    .. _example link: 1.0/ExampleLink

7. Try to use lists for lists and don't bold text or italicize or something. This mostly comes up when dealing with lists of arguments and whatnot, check the `Configuration <1.0/Configuration>`_ page for an example::

       argument 1 explanation text
       argument 2 explanation text

Editor Guidelines

If you bless a page by marking it as official, please send a note to
turbogears-docs saying so. I (Karl) would like to keep track of things
without missing them in the noise of RecentChanges and I'm sure you
would as well.

If you work on a document that is marked official, please

1. take extra care
2. set the status to "Work-in-progress" or "Draft" while you are working on it
   and as long as at least one other person had a chance to look at your changes.

Remember, pages marked with "Official" are considered to be accurate, reviewed
and have proper style. Copy editing is an essential part of maintaining high
quality documents.

.. macro:: [[PageComment2(nosmiley=1, notify=1)]]

ObpBroadview/ContributingDocsToTurboGears (last edited 2009-12-25 07:14:00 by localhost)