Anybody who wants to participate is welcome. The prerequisites for doing so have been reduced down to the bare minimum:
- have an account on spip.net
- know how to use a tag, a criterion, ... that is not documented yet and be able to provide a suitable usage case
- have read this current article to know some of the peculiarities associated with writing SPIP’s documentation
An article’s title
- a filter:
|name_of_the_filter - a tag:
#NAME_OF_THE_TAG - a criterion:
{name_of_the_criterion}
Summarise the item being documented
The standfirst is used to introduce the concept in question:
- one or two short phrases that summarise the introductory text for the item. This text is used in the
<critereXX>and<baliseXX>models (an examples of how this works is here: The ARTICLES loop)
Describe the concept
The Text field is used for the exhaustive description (as much as possible) for the item being documented:
- uppercase letters to start sentences
- use the <code> and </code> tags to surround the item name (e.g. "The
#TAG..."), any URLS into the private zone (e.g. "by looking in?exec=config_fonctions..."), and sometimes the result that will be displayed (e.g. "The date returned will be of the form1970-01-01 00:00:00") - try to use tags that are (more legible) <code> and </code> rather than <cadre> and </cadre>
- structure the text (sub-headings and paragraphs)
- Overall:
- try to concentrate on documenting only the item that is the subject of the article (don’t try and say everything, avoid digressing, not too many tips and tricks, ...)
- check through at a bare minimum (by reading the code) any existing information that is already available
Use keywords
- indicate the version of SPIP which first introduced the item being documented
- indicate the version which (may possibly) have delivered this item
- for tags:
- indicate if it is a static tag (from the database) or a dynamic tag (calculated and processed by a function)
- do the best that you can !!
:-)
... more to follow