Author: Derick Rethans Date: 2006-01-18 12:12:19 +0100 (Wed, 18 Jan 2006) New Revision: 1958
Log: - Added tutorial writing guidelines (draft) Added: docs/guidelines/tutorial.txt Added: docs/guidelines/tutorial.txt =================================================================== --- docs/guidelines/tutorial.txt 2006-01-18 11:06:23 UTC (rev 1957) +++ docs/guidelines/tutorial.txt 2006-01-18 11:12:19 UTC (rev 1958) @@ -0,0 +1,87 @@ +Guidelines to writing a requirements document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:Author: Jan Borsodi +:Revision: $Revision$ +:Date: $Date$ + +.. contents:: Table of Contents + +Format of the document +====================== + +To ensure consistensy 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 - preferrably +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 Property changes on: docs/guidelines/tutorial.txt ___________________________________________________________________ Name: svn:keywords + Author Revision Date Name: svn:eol-style + native -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
