Participating in the documentation of SPIP’s tags, criteria, and filters

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 form 1970-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

Author Mark Published : Updated : 26/10/12

Translations : català, English, français, Nederlands