Guidelines for the translation of the site’s documentation, www.spip.net

-  Order of the articles in the sections

There are two ways to "categorise" the articles on spip.net:

-  for some sections, it is necessary to "force" the ordering of articles according to a certain logic (such as tutorials or reference documents), requiring a lesson to be spanning several successive articles; to do so, insert numbers inside the titles of the articles ("1. First article", "2. Second article", ...);

The Spanish version translators have adopted a very practical solution to order articles: "10. First article", "20. Second article", etc. You are advised to proceed in this way so that articles can later be inserted inside this ordering.

-  inside sections that do not require sequential reading of articles "one after another" (FAQ, tips and tricks, ...), it is better not to order the articles with number. This allows us to show the most recent articles at the top of the list and the oldest below.

In the templates, the presentation adapts itself automatically according to the presence or the absence of numbers.

-  Section logos

Logos have been re-designed so that they no longer contain text (the titles are indicated in HTML in the templates) allowing them to be used again in most languages. Therefore, you are advised to retrieve the French version’s icons and install them again in the corresponding sections in the other languages. The site does not use "hovering logos".

-  Large versions of the Sections’ logos

Each section’s logo comes with a large version that should appear at the top of the sections pages. Similarly, you should retrieve these large versions from the French pages and install in the corresponding sections of the other languages.

These large images will be installed as "documents attached" to the sections (one per section): once you have uploaded these documents, you should give them the title "spip_haut". Having done that, you should click on "View online" to check the result immediately.

For the time being, it is advisable to ensure consistency in the presentation of the sections. Later (when we will hopefully have more time at our disposal), we can work on logos variations according to the languages.

-  The forums in each language

Here, the forums are enabled through a section. As a matter of fact, we keep the basic configuration of the forums in all the site’s articles (i.e. enabled and moderated afterwards), however they are not shown in the templates. But this keeps the door open for future forums "tweaking" in each page according to new developments (such as restoring the FAQs’ "marking" system).

In order to create a "forums" section, you just have to assocate it with the keyword "Forums" in the private area. All the articles published in this section will therefore, "wear" the forums interface.

On spip.net, forums are topic based. The topic is actually the title of the article hosting the forum:
-  to sort the forums "logically", articles’ titles should be numbered (for instance: "1. Installation", "2. Using the private area"...);
-  do not hesitate to write a paragraph or two describing the topic of the forum in the body of the article.

PS: Forums sections related to any one language appear in the left column in all sections pages.

  • Forums moderation

When you create the forum’s article, you are automatically indicated as the author of the article (basic SPIP’s function). If you keep it that way, you will receive an e-mail for every message posted to this article’s forum. This may be practical for the follow-up of the forum’s activity, but it could be awkward if the forum is very active (several message per day). It is up to you to decide if you want to receive those follow-up e-mails.

To stop receiving those e-mails, you just have to remove your name as author of the article. PS. Following the same rule, you can define as author anyone who wishes to receive those e-mails.

Experience taught us that SPIP’s forums become very crowded quickly. The new interface aims at simplifying their use (namely for the search on a question already asked). To ease the archiving function of these forums (I have a problem, I will check if the question has already been asked and answered to), two moderation matters are recommended:
-  questions (i.e. top level messages starting a thread) should have a clear subject (this way the table summarising the questions will be legible, otherwise there will be threads which do not show what they are talking about…); questions with now subject should be deleted (there a big bold warning at the top of the page containing the messages form, so on your head be it…); PS. This will not apply to the replies whose subject is automatically defined as "> The question", which is quite sufficient browse the forum;
-  make sure the questions are asked in the right forum (our experience shows that some users carelessly post their replies anywhere), here as well, messages in the wrong place should be chucked away.

If a message is deleted due to one of the previous reasons and if the question is interesting (clearly formulated, new topic), the message could posted again with the correct subject or to the right forum; in this case, it is advised to indicate that this is a re-posting and quote the original message (<html><quote>...</quote></html>).

Apart from that, SPIP dedicated forums work rather smoothly moderation wise. All in all, there are two types of messages to monitored:
-  messages that disparage a host or a commercial product; this type of messages will almost systematically brings lawsuit threats on us; if the message seems defamatory (such us "the host somehost-online is utter rubbish"), chuck it away and do not hesitate to require from the author of the message to re-write it in a more argumentative way (such as "it is difficult or almost impossible to use SPIP at somehost-online, because such and such…"), which anyway will be of more use to the other participants;
-  messages proposing a technical solution based on PHP and creating a security hole in the sites (such as query the database with passwords directly from the templates); at least, follow immediately with a message bearing warnings in bold or in flashy red or blinking to explain that this bit of code must not be used.

Synchronising the sections presentation and a language’s home page

The new templates reproduce the behaviour of the previous version on uzine.net: the home page is just list of sections / sub-sections and lists of articles. It contains prominent blocks, which synchronise the interface and emphasize some elements. On uzine.net, these blocks where coded directly in the template but now they are automatically updated according to certain criteria.

This allows, among other things, the scraping of the ancient block "Useful information" at the top of the page by inserting this information with emphasis inside the sections or sub-sections list.

-  Emphasizing a referenced / syndicated site

A block appears around a referenced site if a description of this site was added. Therefore:
-  add a description to the sites you want to emphasize;
-  do not add a description for the others.

For instance, here is a tip used in "Questions and answers" in some language versions: we can emphasize an element from spip.net by attaching it as a "referenced site" with a description. This is the case of the "Discussion list of SPIP’s users" and the "Discussion forum": these blocks are created by "referenced sites" and a description with a more advanced layout (adding an image by hand, directly using HTML, introduction to the description in bold,… reminder of the hyperlink inside the description…).

-  An explanatory block in the sub-section

If we enter a text in a section ("Modify this section", "Explanatory text" field), it will appear in a frame in the home page and in parent sections. In the section "Questions and answers" of some language versions, the block "Receive answers" ("Obtenir des réponses") is in fact the explanatory text of the section. PS. the template automatically creates the block, it is not to be coded in the section text.

In the presentation of the sub-sections, it is the article description which appears in a frame. [*]

-  Indicating the discussion list of the language

Each language provides a discussion list (spip-#lang@rezo.net). They are each indicated in the documentation section of corresponding language.

In order to emphasize the list in the section’s home page of a language, you just have to create a "referenced site" which address is the registration page of the list. If you add a description, this "referenced site" will be emphasized in the home page.

Footnotes

[*Like this.

Author George, mathieu, Paolo Published : Updated : 26/10/12

Translations : català, corsu, English, Español, français, italiano, Nederlands, Türkçe