Guidelines to writing a tutorial
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Author: Derick Rethans
:Revision: $Revision$
:Date: $Date$

.. contents:: Table of Contents

Format of the document
======================

To ensure consistency the following format should be employed in the
document. The document should always start with a header which says::

  eZ components: Component
  ~~~~~~~~~~~~~~~~~~~~~~~~

Where *Component* is the name of the component.
The document should start with the following lines, this generates a TOC
automatically: ::

  .. contents:: Table of Contents

The rest of the document should contain the following headers: ::

    Introduction
    ============

The introduction should explain what the component does, and what it can not
do. Also explain for which things this component can be used for - preferably
with a small example (no code, just text).

::

  Class overview
  ==============

In this section you should present all public classes. Their responsibilities,
their features and how they interact with the other classes in this component.
The format is: ::

    ezcClassName
      This class does blah and blah and such and has quite some other
      interesting things that will make you much happier.

::

  Installation
  ============

This section should include what you need to make this component run. You don't
have to explain how to setup the components, instead you can simply point to
the introductory article on ez.no with the following paragraph: ::

  This tutorial assumes that you have set-up an eZ components enviroment. For
  information on how to do this, please refer to the ComponentsIntroduction_.

  .. _ComponentsIntroduction: http://ez.no/community/articles/an_introduction_to_ez_components

After this paragraph you can then explain additional requirements for the
component (for example PHP extension requirements) or for the tutorial (for
example a specific file/directory structure).

::

  Some Other Header
  =================

And then the rest of the document text. Use sections to separate parts and in
text you can simply use ezcClassName->method() for dynamically called functions
and ezcClassName::method() for statically called functions. A script will
convert this to links to the relevant documentation pages.


Conventions
===========

We use RST for the format of the tutorials, please make sure it validates
before committing.
  

..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79 nocin