[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [uk] [vi] [zh] Espace de traduction

Home > English documentation > Contributing > The development of SPIP and its tools > Participating in the documentation of SPIP’s tags, criteria, and (...)

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

August 2010 — updated on : July 2010

All the versions of this article:

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

Show the template of this page Site powered by SPIP | Translation area | Private area