Comment utiliser le centre de documentation

Bienvenue dans le centre de documentation. Cette façon de documenter est un peu différente de ce que vous avez peut-être déjà fait. Veuillez donc lire cette documentation pour comprendre comment contribuer.

En quelques mots

Pour les impatients, voici le minimum de ce que vous devez savoir :

• Vous devez être identifié.
• Il y a différents types de documentation, la plupart compréhensible facilement mais faites attention à la différence entre un how-to et un tutoriel (expliqué ci-dessous).
• Pour ajouter un point de documentation, rendez-vous dans la section correspondante, soyez certain qu'il n'existe pas déjà une documentation correspondant à celle que vous voulez ajouter, et utiliser le bouton situé en haut à droite "Ajouter un ...".
• Ajoutez votre contenu et sauvez-le. Vous pouvez éditer/visualiser le contenu autant de fois que vous le désirez, jusqu'à ce que vous soyez satisfait du résultat.
• Soyez certain de soumettre votre document pour publication quand vous avez terminé - menu déroulant de droite dans la partie "contenu".
• Un modérateur pourra alors ouvrir le document, et le publier à moins que le contenu doive être modifié.
• Si quelqu'un ajoute un commentaire concernant votre document, vous serez averti par mail.

Quel type de documentation devez-vous créer ?

Ci-dessous une description, l'usage et un exemple pour chaque type.

FAQ (question fréquemment posée)

Une FAQ est une question courte avec une réponse en 1 ou 2 paragraphes. Vous pouvez ajouter plusieurs questions dans une FAQ et les grouper dans des sections:

Exemple de FAQ
Question: Qu'est-ce que Plone?

Réponse: 
Plone est un logiciel libre de gestion de contenu (CMS)
qui fonctionne avec les logiciels Zope et CMF. 

How-to (comment faire ...)

Un how-to est une description en une page décrivant la façon d'accomplir quelque chose. Ce contenu est de type "dossier", des images et documents peuvent y être attachés. Un how-to est court et va à l'essentiel.

How-to typiques:

• Comment configurer Plone avec un serveur Apache
• Comment changer les onglets qui apparaissent en haut du portail

Tutoriel

Un tutoriel est un article en plusieurs pages contenant beaucoup de détails. Le tutoriel est plus précis qu'un how-to , et peut contenir les aspects conceptuels de la tâche, en complément aux étapes pratiques pour la réaliser.
Si vous êtes incertain de la différence entre un how-to et un tutoriel, pensez à la différence entre une recette qui contient les ingrédients nécessaires et la façon de les mélanger (how-to), et un article expliquant tout ce qui concerne le cake, sans forcément la façon de le préparer (tutoriel).

Tutoriels typiques:

• Comment utiliser les workflows dans vos projets
• Pourquoi séparer le contenu, la logique et la présentation

Manuel de référence

Un manuel de référence est un document complet concernant un produit ou une technologie, contient un certain nombre de pages, avec des sections structurant le contenu.

Lien (dans le centre de documentation)

Un lien peut être externe ou interne. Il est différent d'un lien Plone standard car il peut avoir des sections et une notion de version.

Liens typiques:

• Le livre Zope sur zope.org
• Le manuel de référence CSS sur W3C

Référence d'erreur

Une référence d'erreur est une explication concernant une erreur particulière, avec les détails sur la manière de résoudre le problème.

Références d'erreur typiques:

• String attendu, integer obtenu
• La page template contient des erreurs :  compilation échouée

Glossaire de définition

Un glossaire de définition explique un terme particulier de façon concise.

Glossaires de définition typiques:

• CMF: content management framework (outil de gestion de contenu)
• Workflow: un système structuré en états et transitions, utilisé pour modéliser des processus