Documentation en cours d'écriture
Voici des documentations ayant été notées comme “en cours d'écriture” et qui ne sont donc pas terminées.
Si vous avez des idées de rédaction de tutoriel et quand bien même cette idée ne ferait pas partie de la liste ci-dessus venez participer ! Votre idée est certainement intéressante !
Voici quelques éléments à prendre en compte lors de l'écriture d'une documentation :
Pour entrer dans LibraZiK, il faut au minimum une page “logiciel” de présentation du logiciel. Ces pages sont standardisées.
Les pages “logiciels” fournissent les caractéristiques principales d'un logiciel : son utilité, là où on le trouve, des ressources externes en français si possible,… + une information du “paquet” dont il provient + un lien vers les “tutoriels” qui parlent de lui + 2 ou 3 autres petites choses.
Ces pages sont donc un “descriptif” général du logiciel. Une fois que cette page est faite, on peut passer à une “mise en situation réelle d'utilisation”, aussi appelée un “tutoriel”.
Ils seront présents dans la page “Tutoriels” du bandeau noir en haut du site. Il est très très très très encouragé d'avoir une page de tutoriel de type “premier pas” étant hyper-précise et qui explique pas à pas comment utiliser ce logiciel à travers un exemple d'utilisation.
Il n'est pas nécessaire que cette page couvre l'ensemble des possibilités du logiciel, l'idée des tutoriels “premier pas” étant plutôt de permettre à quelqu'un qui est totalement débutant de pouvoir sortir un son du logiciel.
Une pratique importante et très encouragée (mais pas obligatoire) dans le cadre des tutoriels “premier pas” est de faire ces tutoriels à cheval sur 2 logiciels. Ceci expliquant par l'exemple la tradition d'utilisation des logiciels libres où chacun d'entre eux fait une chose puis se relie avec d'autres.
Une autre chose importante pour les “tutoriels premier pas” est de faire des captures d'écran à partir d'un système LibraZiK-2 fraîchement installé pour que le lecteur suivant ce tutoriel ne soit pas bloqué par un paquet non-installé ou une configuration non-faite.
Dans les tutoriels, on peut éventuellement ajouter une “FAQ” à la fin, voir par exemple : le paragraphe FAQ de la page QjackCtl.
Ils seront présents dans la page “Tutoriels” du bandeau noir en haut du site. Il s'agit principalement d'un descriptif précis et si possible exhaustif de l'interface graphique d'un logiciel.
Ceux-ci ne figureront pas dans le lien “Tutoriels” du menu, mais seront présents dans la liste de tutoriels de chaque page de logiciel.
Ce type de tutoriel n'a pas besoin d'être autant détaillé que les tutoriels “premier pas”. Ceci dit, il est conseillé de mettre dans les pré-requis (en début de page) un lien vers un tutoriel de type “premier pas” où sont abordés toutes les techniques et compétences nécessaires non-détaillées dans un tel tutoriel. Si un tel tutoriel “premier pas” n'existe pas encore, alors il conviendra de le faire en premier lieu.
Les pages concernant les paquets de greffons sont également standardisées. LibraZiK fournit une page générale pour le paquet de greffons, et une page dédiée par greffon. C'est un gros travail, c'est certain. Ceci à le mérite de considérer chaque greffon comme un logiciel à part entière, et de permettre à une personne débutante d'avoir toutes les informations dont elle a besoin pour démarrer correctement. Ceci permet aussi grâce aux “tags” de pouvoir effectuer une recherche précise.
Les infos dans ce type de page de présentation de chaque greffon sont toujours classées de la même façon 1) et sont donc un genre de “fiche du logiciel” :
Des pages de tutoriels d'utilisation sont également les bienvenues pour chaque greffon.
Pour les pages “logiciels”, ainsi que les pages de “tutoriels”, il y a un système de “tags” en place qui leur permet de s'intégrer correctement et (presque) automatiquement toutes seules dans les pages utiles.
Regardons par exemple un tuto “premier pas” : zynaddsubfx_qjackctl_clavier_midi qui parle de zynaddsubfx et de qjackctl, et qui est également un tutoriel de type “premier pas”.
Si l'on regarde en bas de la page, il possède (entre autres) des “tags” : “tutoriel qjackctl”, “tutoriel zynaddsubfx” et “premier pas” qui permettent à cette page d'être listée dans les pages de qjackctl, de zynaddsubfx, et dans la section “premier pas” de la page “tutoriels” de bandeau noir.</note>
Pour faire des captures d'écran, il est encouragé d'utiliser l'outil de capture d'écran de MATE. Utilisez à bon escient la possibilité de l'outil MATE de ne capturer que la fenêtre active. Ceci permet entre autre d'obtenir une fenêtre sans une bordure de 10 ou 15 pixels de ce qu'il y a en arrière plan, et c'est vraiment moins moche.
Une autre possibilité est d'utiliser l'outil de GIMP.
Pour la retouche des images, l'utilisation de GIMP permet de faire du bon boulot.
Pensez à ajouter une “ombre portée” ce qui améliore le rendu de l'image lors de son affichage sur une page de documentation en lui promulguant un effet de relief.
Pour appliquer un encadrement, des flèches, ..etc, utilisez la couleur verte de code couleur : #008800 pour conserver une cohérence à travers la documentation.
Essayez de ne pas dépasser une centaine de kilo-octet par image.
Ne pas trop les réduire en taille de pixel non plus car le wiki permet de les redimensionner à la taille que l'on veut (souvent plus petite) ce qui permet d'avoir la possibilité, lorsque l'on clique dessus, de les voir en grand.
