============================
Comment documenter un projet
============================
----------------
Avant d'attaquer
----------------
Lorsque l'on fait une simple recherche sur internet avec les mots clefs : ::
comment documenter un projet
On se rend compte qu'il y a déjà beaucoup d'informations disponible sur ce sujet. Je n'hésiterai
d'ailleurs pas un instant en vous renvoyant de temps à autres vers l'un ou l'autre de ces sites.
:Liens_Web:
* http://cours.education/dufacilitateur/2016/07/24/atelier-comment-documenter-son-projet-v1/
# Une aide à la documentation proposée par le FacLab
* http://carrefour-numerique.cite-sciences.fr/fablab/wiki/doku.php?id=aide:documenter
# Une aide à la documentation proposée par Le Carrefour Numérique
* http://blog.wikifab.org/2016/07/19/pourquoi-documenter-et-partager-mon-projet/
# Une description de pourquoi, pour qui donnée par WikiFab
* https://reso-nance.org/wiki/_media/projets/documentation-fablab.pdf
# Un petit PDF résumant les étapes de documentation
* http://www.fao.org/capacity-development/resources/practical-tools/comment-documenter-et-partager-les-bonnes-pratiques-pour-generer-le-changement/fr/
# Comment capitaliser et partager vos bonnes pratiques pour générer le changement
Pourquoi encore un document sur "comment faire de la doc"
=========================================================
Tous d'abord parce qu'il est toujours intéressant d'avoir plusieurs points de vue sur un sujet
lorsque l'on décide de s'y intéresser, pour pouvoir se forger sa propre opinion. Ensuite ce document
n'est pas quelque chose que vous devrez suivre à la lettre pour avoir la garantie de faire une bonne
documentation. Il s'agit simplement de vous décrire au mieux ma propre recette. Vous pourrez ainsi
piocher (ou non) quelques idées pour définir votre propre méthode.
Ce document apporte en plus des éléments sur la façon de gérer et d'organiser un projet, ce qui
peut être utile si vous n'avez pas encore défini votre propre méthodologie de gestion de projet.
####
------------------------------------------------------------------
Les bonnes questions qu'il faut se poser pour documenter un projet
------------------------------------------------------------------
Il y a deux thèmes importants dans la documentation :
* **Pour qui et pourquoi** : ce thème permet de définir la cible principale à qui
s'adresse la documentation
* **Quoi et comment** : ce thème permet de définir les outils nécessaires à la documentation et
à l'organisation de votre projet.
####
----------------------
Pour qui et pourquoi ?
----------------------
Dans la plupart des lectures que j'ai pu consulter, il revient une idée générale avec laquelle je
ne suis pas d'accord. Cette idée, c'est :
*"Il faut documenter afin de partager son travail avec d'autres personnes"*
Pour ma part, je pense que le travail de documentation doit d'abord être un travail égoïste. La
documentation doit être faite en priorité pour soi, mais écrite pour quelqu'un qui ne sait pas de
quoi il s'agit et qui découvrirai complètement votre projet. De cette façon la documentation sera
plus complète et plus précise.
:Exemple: Imaginez que vous soyez tout le temps en train de faire 50 trucs en même temps,
plus les activités des enfants, le travail, les courses etc ... (dur à imaginer
n'est-ce pas ? :p ). Dans cette situation il peut arriver qu'un projet soit mis de
coté pendant plusieurs mois voire plusieurs années.
Lorsque vous allez enfin pouvoir reprendre votre projet, vous aurez oublié une
grande partie du million de détails qui constituent votre projet. Trois choix se
présentent alors :
* Vous reprenez le projet depuis le début pour essayer de comprendre comment
vous avez fait telle opération ou pourquoi vous aviez privilégié une solution
plutôt qu'une autre.
* Vous remettez votre projet sous les tas de poussière sous lesquel il était
enterrer et vous vous empressez de l'oublier consciencieusement car le
reprendre depuis le début représenterait un investissement en temps et en
pressage de citron beaucoup trop important.
* Vous ouvrez simplement la documentation que vous avez pris soin d'écrire tout
au long du projet, ce qui vous permet de reprendre rapidement et facilement
vos travaux.
Vous l'aurez compris, vous êtes le premier destinataire de la documentation que vous allez produire.
Cependant, comme vous aurez pris la peine de vous faire une doc (et donc elle existe déjà), il ne
vous reste plus qu'à la partager avec la Terre entière puisque que cela ne vous coûtera pas plus
de travail.
####
-----------------
Quoi et comment ?
-----------------
**Que faut-il mettre dans la documentation ?**
A cette question ma réponse est : Tous ce que vous pouvez !
* Toutes les idées que vous avez eues, celles que vous avez expérimenté, pourquoi certaines
n'ont pas été conservées, pourquoi les autres oui.
* Tous les croquis que vous avez dessinez sur un coin de nappe (avant de vous apercevoir
qu'elle était en tissu ;) )
* Vos succès, vos échecs, vos erreurs
* Les objectifs majeurs, mineurs et transitoires du projet
* La fiche de description du projet
* les plans de fabrication
* Les listes des matériaux avec leur provenance et leur prix
* les schémas électroniques, les typons et les PCB
* La liste des composants électronique avec leur provenance et leur prix
* le code source du programme
* Les sources des informations que vous utilisez pour avancer dans votre projet
En résumé, tous ce que vous avez produit ou utiliser pour réaliser votre projet.
**Il ne faut jamais trop se faire confiance.**
Si vous pensez :
*"ça c'est bon, je m'en souviendrai. Je n'ai pas besoin de le noter !"*
Ou :
*"c'est parfaitement compréhensible, je n'ai pas besoin de l'expliquer !"*
Vous pouvez être certains que NON vous ne vous en souviendrez pas et que NON ce n'est pas si
compréhensible que ça quand vous n'avez pas touchez au projet depuis 6 mois. Il vous faut donc
systématiquement noter et documenter même les choses évidentes et / ou apparemment simple.
**Soyez clair et efficace dans vos explications.**
N'hésitez pas à lire à haute voix ce que vous avez écrit. Cela vous aidera à définir si ce que
vous avez écrit est :
* Suffisamment explicite
* Pertinent
* Pas trop compliqué. Pas besoin d'avoir une doc pour comprendre la doc
(qui a dit : "meuble Ikéa" ?).
* Pas trop verbeux. Il s'agit d'une documentation, pas d'un essai littéraire. Il ne faut pas que
les informations soit perdues dans un flot de blablas inutile.
Des images Oui, mais pas que !
==============================
L'ajout d'image, de croquis, de graphique ou d'illustration est toujours une bonne chose car cela
peut aider à la compréhension. Attention toutefois à ne pas en abuser. Il ne faut pas transformer
votre doc en BD ou en rébus.
* Ajoutez un support visuel que si ça amène une plus-value à votre doc.
* Accompagnez toujours vos illustrations d'une légende et / ou d'un commentaire.
* Ne pas concentrer trop d'informations visuelles au même endroit, car cela masque le texte qui
est souvent plus important.
.. image:: ./Images/Deco/ampoule.png
:width: 50px
:height: 50px
:align: left
:Petites Astuces:
#. Pour identifier plus facilement à quel projet une image appartient (en
particulier si vous publiez votre doc sur un WIKI), vous pouvez ajouter un
préfixe au nom de votre image. ::
ex:
projet : "patate au four"
image : "carrotte_bleu.jpg"
Nom de l'image associé au projet
PAF_carrotte_bleu.jpg
Boite à idées
=============
Une idée n'est bonne que si on s'en souvient !
C'est toujours une bonne pratique que de noté toutes vos idées dans un document. Vous pouvez avoir
plusieurs boites à idée. Une globale dans laquelle vous allez décrire les idées qui vous permettront
de commencer d'autres projets qui n'auront peut-être rien à voir les uns avec les autres. Et une par
projet qui vous servira à améliorer ou à développer votre projet.
.. image:: ./Images/Deco/ampoule.png
:width: 50px
:height: 50px
:align: left
:Petites Astuces:
#. Tant que vous n'avez pas commencer le projet, laissez-le dormir dans
la boite à idées. Cela vous évitera d'avoir des tonnes de dossiers projets
vide qui ne contiennent en tout et pour tout que la description globale de
votre idée.
#. Utilisez, pour votre boite à idées, la même structure / arborescence que
pour vos projets.
Souvent lorsqu'on a une idée, elle nous enthousiasme tellement qu'on a
tendance à faire tout de suite des recherches dessus. Si vous avez
organisé votre boite à idée comme un projet, vous allez pouvoir y stocker
le fruit de vos recherches en attendant que votre idée devienne un vrai
projet.
Documenter régulièrement
========================
La plus grosse erreur que vous pouvez faire c'est de vouloir faire la documentation quand tous le
reste sera terminé. Si vous vous dites cela, vous pouvez être certain que vous ne ferez pas de
documentation. Voici par exemple certaines raisons qui vous en empêcherons :
* Il y a de grandes chances pour que vous enchainiez directement sur un autre projet.
* Vous n'aurez pas le temps car vous serez trop occupé ailleurs (souvenez-vous, la vie, le
travail, les enfants tout ça).
* Faire la documentation en dernier équivaux à recommencer tout le projet depuis le début. On
se retrouve dans la même situation que celle qui a été donné en exemple un peu plus haut. Je
suis certain qu'à ce moment vous serez atteint d'un mal assez connu que l'on nomme :
"La flemme".
Pour éviter cette situation il faut documenter régulièrement vos travaux, consigner toutes vos
expérimentations, prendre des notes sur vos manipulation (voir "`Le Journal de Manip`_") et si
possible faire une fiche descriptive du projet à partir de laquelle vous pourrez définir plusieurs
petits objectifs qui seront plus faciles à réaliser et donc à documenter.
Journal de manip, Bug et TODO list
==================================
Le Journal de manip
-------------------
Un projet n'est jamais réalisé de façon linéaire. Vous serez souvent amené à vous détourner de
votre objectif principal afin de découvrir de nouvelles choses, expérimenter une nouvelle
technique, tester un outil ou une appli ou encore tester du matériel. Tout cela représente de
l'expérience.
L'expérience, c'est comme les idées. Cela ne sert à rien si on ne les conserve pas. Pour éviter de
perdre toutes ces précieuses expériences, vous pouvez créer **un journal de manip**.
Le journal de manip, est un document dans lequel vous allez noter tous ce que vous avez pu faire ou
tester sur un sujet donné. Vous pouvez faire un journal de manip par projet, mais je vous conseil
de faire un journal de manip global car au cours de vos différents projets vous allez certainement
travailler sur des thèmes communs ou similaires.
Ce journal de manip vous servira également de support pour votre documentation.
Vous pouvez consulter mon propre `journal de manip `_. Je ne
l'ai pas organisé comme un journal dans lequel je saisie toutes mes manips au quotidien, mais comme
un référentiel technique dans lequel je répertorie les éléments sur lesquels j'ai été amené à
travailler une ou plusieurs fois.
A vous de trouver l'organisation qui vous convient le mieux pour la gestion de votre
Journal de manip.
Bug et TODO list
----------------
Tout au long du développement de votre projet, vous allez le tester et le faire évoluer. Au cours de
ces tests, il arrive souvent que l'on constate un défaut ou un point qu'il faudra améliorer. Si ces
défauts ne sont pas bloquant, il n'est pas nécessaire d'interrompre le travail en cours. Cependant,
pour ne pas oublier que ces choses sont à faire, je vous conseille de créer un document dans lequel
tous ces problèmes sont référencés.
Voici le modèle que je me suis défini : ::
Model Type
==========
:Date de saisie: Date à laquelle la problématique a été identifiée
:Date de traitement: Date du traitement de la problématique
:Cible: [userDoc, modelisation, software, PCB, autre]
:Statu: [NONE, WIP, DONE]
:Problématique: Descriptif de la problématique
:Traitement: Descriptif du traitement de la problématique
Comme vous pouvez le constatez le modèle est assez simple. Les 2 seuls éléments qui peuvent poser
problème sont :
* **Cible** : C'est ici que je renseigne la "catégorie" de l'élément impacté comme la doc, le
programme, le matériel, etc. Ces éléments sont extraits de ma propre `arborescence de projet `_
que vous pourrez découvrir un peu plus bas.
* **Statu** : C'est ici que je renseigne l'état d'avancement du travail à faire
- None : Le travail n'est pas commencé
- WIP : (Work In Progress) Travail en cours
- Done: Travail fini
Vous pouvez consulter le fichier `Bug_ToDoLst `_
de ce projet pour voir comment je l'utilise.
Tout comme moi, vous pouvez intégrer ce document à la documentation du projet.
**N. B** : N'hésitez pas à joindre tous vos documents de travail dans votre documentation car ils
représentent de l'information que vous serez content d'avoir après une longue pause dans le projet
.. image:: ./Images/Deco/ampoule.png
:width: 50px
:height: 50px
:align: left
:Petites Astuces:
#. Il arrive souvent que nos idées nous viennent au cours d'un moment d'oisiveté,
d'un moment de détente ou tous simplement quant ce n'est pas le moment. Pour
être certain de conserver cette brillante idée jusqu'a ce que vous soyez
enfin devant un PC, prenez l'habitude de toujours avoir avec vous un petit
blocnote et un stilo. Vous pourrez ainsi preserver votre idée des courrant
d'air en la gardant bien au chaud. Vous n'aurez plus ensuite qu'à l'étofer et
à l'ajouter au reste de votre documentation.
Un peu d'organisation
=====================
De façon générale, vous ne pourrez pas travailler efficacement si vous ne tentez pas un tout petit
peu de vous discipliner et d'organiser votre espace de travail et votre travail lui-même.
Il y a quelques bonnes pratiques que vous pouvez adopter. Vous les trouverez peut-être un peu
contraignantes au début mais lorsque vous vous y serez habitué, vous serez content de retrouver
toujours les mêmes types d'éléments au même endroit.
Un peu de paresse est bon pour la santé
---------------------------------------
Si vous faite de la programmation, vous avez peut-être déjà rencontré l'expression DRY (Don't
Repeat Yourself) qui signifie : Ne te répète pas toi-même.
Il faut faire attention à ne pas se répéter. Il serait dommage de documenter 2 fois une partie du
projet parce que cette partie en question est référencer à plusieurs endroits dans votre bazar
(pas si) organisé.
On peut également étendre le concept à : ne répètes pas ce que les autres ont déjà dit. Il est
inutile de faire du copier-coller (ou même de réécrire) quelque chose qui a déjà été écrit. Il
suffit de mettre un lien dans votre documentation pointant vers l'endroit où l'information existe
déjà.
**N.B** : N'oubliez pas de cités les sources et les auteurs des informations d'une tiers partie que
vous incorporez dans vos documents.
Uniformiser les projets
-----------------------
Lorsqu'on travaille sur un projet, on peut être amené à manipuler de nombreux éléments différents
comme :
* le code source d'un programme
* les schémas électroniques
* des plans de fabrication
* les docs techniques que vous avez récupérés à droite, à gauche
* Vos propres notes et documentation
* ETC.
Pour gérer ces documents, vous avez plusieurs solutions :
* **Tout réunir dans un seul dossier** : Vous aurez tous les éléments au même endroit mais il
n'y aura certainement pas d'organisation logique
* **Tout répartir à différents endroits sur votre disque dur** : Vous aurez un semblant
d'organisation mais il deviendra difficile de partager votre projet en l'état. Vous serez donc
obligé de regrouper tous les éléments en un même endroit quand vous souhaiterez le diffuser.
Créant ainsi un doublon des différents éléments et augmentant la difficulté de maintenir le
projet.
* **Une troisième solution** et de créer un dossier pour le projet et de créer des sous
répertoire pour l'organisation des différents documents. Vous aurez donc tous le projet dans
un seul répertoire, une meilleure organisation du projet et une meilleure facilité de
maintenance et de diffusion.
La troisième solution est la bonne, mais comment allez-vous organiser le prochain projet ? En créant
un nouveau dossier principal et une nouvelle sous arborescence.
C'est à ce moment qu'il faut un peu de discipline (ce que j'appelle la paresse organisée). Vous
devez-vous définir une arborescence standardisée dans laquelle vous aurez toujours les mêmes noms de
dossiers et les mêmes modèles de fichiers. Ce qui vous permettra de ranger les différents types de
documents toujours de la même façon quel que soit votre projet.
Vous devez utiliser la même arborescence dans tous vos projets pour vous faciliter le travail
Voici en exemple l'arborescence que je me suis défini ::
ProjectDir_Name # Dossier racine du projet (non versionner)
|
+--project # (Branch master) contient l'ensemble du projet en lui même
| |
| +--_1_userDoc # Contient toute la documentation relative au projet
| | |
| | \--source # Dossier réunissant les sources utilisées par Sphinx
| |
| +--_2_modelisation # Contient tous les plans et toutes les modélisations du projet
| |
| +--_3_software # Contient toute la partie programmation du projet
| |
| +--_4_PCB # Contient toutes les parties des circuits imprimés (routage,
| | # Implantation, typon, fichier de perçage, etc.)
| |
| +--_5_techDoc # Contient toutes les documentations techniques des différents composants
| | # ou éléments qui constituent le projet. Ces éléments sont identifiés
| | # par un liens Web dans la documentation. Ce dossier n'est pas "poussé"
| | # dans le dépôt distant (.gitignore).
| |
| +--_6_research # Regroupe toutes les recherches relatives à l'élaboration ou au
| | # développement du projet. Ces éléments sont identifiés
| | # par un liens Web dans la documentation. Ce dossier n'est pas "poussé"
| | # dans le dépôt distant (.gitignore).
| |
| \--_7_rushes # Contient tous les éléments qui seront potentiellement intégrés dans la
| # doc ou dans le projet. Ce dossier n'est pas "poussé" dans le dépôt
| # distant (.gitignore).
|
\--webDoc # Dossier racine de la documentation qui doit être publiée
|
\--html # (Branch gh-pages) C'est dans ce dossier que Sphinx va
# générer la documentation a publié sur internet
Pour être certain d'utiliser toujours la même arborescence, vous devez limiter le nombre d'actions
à faire à la main. Pour cela, vous avez 2 solutions :
* **Solution 1** : Créer un modèle de projet (avec toute son arborescence). A chaque nouveau
projet, vous copiez le modèle à l'endroit où vous voulez créer votre projet et vous renommer
cette copie avec le nom du projet.
* **Solution 2** : Vous vous faites un petit programme qui va créer pour vous tout les répertoires
et sous répertoire nécessaires. Ce genre de programme est très simple à faire et ce quel que
soit le langage de programmation que vous utilisez. Vous pouvez faire en sorte que ce
programme mette en place une structure plus évoluée comme par exemple : initialiser GIT et
Sphinx en même temps que la création de l'arborescence du projet.
La deuxième solution est plus compliquée à mettre en œuvre, mais elle vous facilitera vraiment le
processus de création d'un nouveau projet.
Vous pouvez regarder mon projet `ArboProject `_ écrit
en python. Ce programme me crée une arborescence, copie ou crée certains fichiers, initialise GIT et
Sphinx dans la foulée. De plus je peux modifier mon arborescence en modifiant simplement un fichier
JSON.
.. image:: ./Images/Deco/ampoule.png
:width: 50px
:height: 50px
:align: left
:Petites Astuces:
#. Si vous utilisez toujours la même arborescence, vous aurez forcement des
dossiers vides. Pour être sûre de ne pas passer votre temps à ouvrir ces
dossiers vides ajoutez le suffixe '_v' au nom de chaque dossier. Vous pouvez
même le faire directement dans votre modèle. De cette façon, lorsque vous
ajoutez des données dans un dossier, il vous suffit de retirer se suffixe
pour obtenir immédiatement un indicateur visuel sur l'état (data ou vide)
d'un dossier. ::
Ex:
# Pas de données
|
\--_1_userDoc_v
# Dossier avec données
|
\--_1_userDoc
|
\--MaSupperDoc.txt
#. En plus d'une arborescence standardisée, il est aussi possible de créer un
certain nombre de fichiers qui seront toujours structurés de la même façon. Je
vous conseille de créer un fichier : README à la racine de votre projet. Ce
fichier devrait contenir les éléments suivants :
* Le ou les auteurs du projet (normalement vous)
* Le ou les relecteurs / correcteurs de la documentation
* `La licence `_ sous laquelle le projet est distribué
* les informations sur la documentation et sur le dépôt (endroit de mise
à disposition) du projet.
* le numéro de version de la documentation
* Une brève description du projet,
* Quelques informations permettant le démarrage ou la prise en main du
projet
* Quelques informations supplémentaires comme par exemple l'arborescence
du projet
Mon programme 'arboProject' me crée se fichier automatiquement. Je fais
systématiquement apparaître ce fichier en premier dans ma documentation.
Vous pouvez consulter le `fichier README de ce projet `_
pour voir à quoi cela ressemble.
Versionner et nommer les fichiers
----------------------------------
Versionner des fichiers
+++++++++++++++++++++++
L'un des problèmes que l'on rencontre souvent est :
"*qu'elle est la bonne version du fichier à utiliser et comment le nommer de façon intelligente
et compréhensible ?*"
:Exemple: Vous venez de terminer le travail sur un fichier. Étant certain que vous n'aurez plus
à travailler dessus, vous le renommer en 'final': '*mon_super_fichier_final.txt*'.
Seulement, le lendemain, vous vous apercevez qu'en fait vous avez oublié de parler
d'un truc important. Vous modifier votre fichier et là cette fois c'est sûr, c'est
la version finale. Comme vous ne voulez pas écraser l'ancien fichier, vous
l'enregistrer en tant que '*mon_super_fichier_final_final.txt*'. Puis quelques mois
après, vous faites une nouvelle modif alors vous enregistrez le fichier sous :
'*mon_super_fichier_final_final_V1.txt*'.
Je pense que vous avez compris où je voulais en venir.
Pour éviter ce genre de problème il existe une technique simple que l'on nomme : "l'horodatage".
Cette technique consiste à ajouter, en préfixe, la date en version courte au nom de votre
fichier. Ce préfixe est formaté de la façon suivante : ::
AAAAMMJJ
Vous pouvez encore simplifier cette notation en considérant que vous ne modifierez pas ce fichier
dans 100 ans ou dans 1000 ans. Cela donne : ::
AAMMJJ
Votre ficher aura alors la forme : ::
AAMMJJ_[Nom_du_fichier].ext
Ex:
'180825_mon_super_fichier.txt'
Pour ma part je me contente de préfixer mes fichiers avec la date. Il peut malgré tout y avoir des
situations ou vous souhaiterez avoir une information plus précise sur l'horodatage du fichier. La
solution est alors d'ajouter l'heure en plus de la date : ::
AAMMJJ-HHMM[SS]_[Nom_du_fichier].ext
# N. B : on peut ne pas spécifier les secondes
Ex:
'180825-1843_mon_super_fichier.txt'
Cette technique présente plusieurs avantages :
* Vous évitez les noms prêtant à confusion
* Vous pouvez repérer immédiatement la version du fichier que vous souhaitez consulter
simplement en consultant son nom
* Lorsque, dans votre explorateur de fichier, vous classerez vos fichiers par nom, ceux-ci seront
également automatiquement classé par ordre chronologique
C'est tout l'intérêt d'écrire l'année en premier, suivi du mois !
Versionner tout un projet
+++++++++++++++++++++++++
Dans la vie d'un projet, il est parfois nécessaire de tester une partie sans défaire la partie déjà
fonctionnelle. Pour cela, il faut pouvoir créer une version fonctionnelle et une version d'essais.
La technique de l'horodatage est efficace au niveau des fichiers, mais pas au niveau des projets.
La solution est donc d'utiliser un logiciel gestion de version. Le plus connu (et le plus utiliser)
est GIT. Les liens sont disponibles dans `Les outils de production`_.
GIT permet de conserver toutes les versions de tous les fichiers. Il offre ainsi la possibilité de
comparer la version actuelle avec une version antérieure d'un fichier. Il permet également de créer
plusieurs branches de travail :
* La branche **'Master'** : C'est la branche principale (Obligatoire). Elle est utilisée pour les
versions Stable et / ou fonctionnelles des projets.
* La Branche **'gh-pages'** : Cette branche devra obligatoirement être créer si vous utilisez la
fonctionnalité de gestion / publication de la documentation de GitHub : github.io
* Les autres branches que vous devrez créer, sont utilisées pour les versions de développement
ou pour tester de nouvelles fonctionnalités.
Il s'utilise en ligne de commandes et permet de porter vos projets vers des dépôts distant comme
GitHub ou GitLab (voir `Les outils de publication des projets et de la documentation`_)
Pour les allergiques à la ligne de commande, il existe Tortoise (`Outils de production `_)
qui est une interface graphique pour GIT. Il s'intègre dans le menu contextuel de Windows.
Version et révision
^^^^^^^^^^^^^^^^^^^
:Liens_Web:
* https://fr.wikipedia.org/wiki/Version_d%27un_logiciel
# Page d'explication des versions logiciel
* https://semver.org/lang/fr/
# Gestion sémantique de version
Il est important, pour vous aussi bien que pour d'autres personnes qui souhaiteraient utiliser votre
projet ou consulter votre documentation, d'avoir des numéros de versions sur vos documents ou
autres éléments du projet.
Il est toujours difficile de définir une bonne nomenclature pour affecter un numéro de version.
Cette décision vous revient. Il y a plusieurs écoles sur ce point. La plus courante étant :
"SemVer" (Semantic Versioning). ::
Majeur.Mineure.correctif
ex:
2.6.2 --> le correctif 3 (la numérotation commence à 0) pour la révision Mineure 6 de la version 2
Consultez les liens ci-dessus pour plus de détail.
Pour ma part je préfère ne pas utiliser SemVer car je trouve se procéder trop contraignant. Puisque
mes projets sont construits dans le temps, j'utilise la date comme numéros de versions. Pour
différencier les versions de développement des versions stables (en plus de ma gestion des Branches
dans GIT), j'ajoute le suffixe "-dev" à la suite de la date. ::
Format:
AAAAMMJJ
ex:
20180913
# version stable
20180914-dev
# version en cours de développement
On constate que je pourrais simplifier mes numéros de version en supprimant les 2 premiers digits de
l'année. Malheureusement, je n'y avais pas pensé quand j'ai adopté ce système de notation. Par
soucis de cohérence, je continue donc avec ce format.
Vous comprenez pourquoi il faut y réfléchir avant d'adopté un système de notation. Si vous décidiez
de changer votre façon d'affecter des numéros de version, sachez que cela pourrait vous gêner par la
suite dans vos gestions de projets, mais cela reste acceptable tant que vous restez cohérent sur les
différentes versions d'un même projet. **Un changement de nomenclature ne peut donc être effectué qu'a partir
d'un nouveau projet.**
Je fais apparaître ces numéros de versions au début de mes programmes. Lorsqu'il s'agit d'un projet
orienté "blablas" comme le présent document, je le place dans le document "`README `_"
qui est présent dans tous mes projets (`voir : Uniformiser les projets `_).
Nommer les fichiers et les dossiers correctement
++++++++++++++++++++++++++++++++++++++++++++++++
Beaucoup d'entre vous l'ignorent, mais on ne doit pas nommer les fichiers n'importe comment. Il y a
des règles de syntaxe à respecter. Là où les systèmes d'exploitation font des pièges (Windows en
particulier), c'est que bien qu'on ne doive pas nommer les fichiers n'importe comment, le système ne
nous l'interdit pas.
Je vous encourage à consulter le site ci-dessous pour prendre connaissance des contraintes de
nommage des fichiers.
:Liens_Web:
* https://bpmi.geneses.fr/3-2-nommer-dossiers-fichiers/
# Page d'explication sur le nommage des fichiers
Voici un résumé de ce qu'il faut faire ou pas
* Pas d'espace
* Pas de caractère "bizarres" ou accentués
* Ne pas utiliser des noms trop longs
* Utiliser uniquement les 26 caractères de l'alphabet (Majuscule et / ou minuscule), les
chiffres de 0 à 9 et les caractères '_' et '-'.
Il est important de respecter ses règles de nommage car les outils que vous allez utiliser comme :
Le Raspberry Pi (ou toutes les machines linux), Github, Wikimedia (et tous le WEB en général),
Sphinx, Doxygen et bien d'autre encore, respectent ces règles.
Ne pas multiplier les copies d'un projet
----------------------------------------
Une chose importante à laquelle il faut être vigilant, c'est de s'assurer que vous travaillez
toujours sur la même source d'un projet (ou de la documentation).
:Exemple: Admettons que vous ayez le dossier de votre projet en local sur votre PC
sur "*D:\\Mon_Super_Projet\\*". Vous pourriez envisager que votre disque dur risque de
tombé en panne. Vous allez alors vouloir en mettre une copie sur le
réseau : "*\\\\serveur_en_reseau\\Mon_Super_Projet\\*". Lorsque vous publierez votre
projet, vous allez à nouveau mettre une copie de votre projet sur un dépôt distant.
Dans cet exemple, vous vous retrouvez alors avec trois versions de votre projet. Ce qui signifie que
vous allez devoir maintenir ces trois versions à chaque évolution de votre projet. Cela demande
beaucoup de temps et de rigueur. Cela vous ajoute autant de risque de faire des erreurs comme :
oublier de modifier l'une des versions ou encore modifier la mauvaise version.
Pour éviter cette gestion difficile, voici ce que vous pouvez faire.
* **Travail en réseau** :
- Si vous êtes en entreprise, vous ne devez travailler que sur le serveur. Aucune copie en
local sur votre poste. L'administrateur réseau de votre société fait des sauvegardes du
serveur, mais pas de votre poste.
- Si vous êtes un particulier, à moins d'avoir un logiciel qui sauvegarde vos données
automatiquement sur un média externe comme par exemple "Cobian Backup", Je vous
déconseille la copie d'un projet sur un média externe (ou un disque réseau), surtout si se
média externe et également un support de travail. Vous éviterez ainsi de travailler sur
deux versions en parallèle.
Il peut arriver que l’on n’ait pas le choix, notamment dans le cas ou vos projets sont stockés
bien au chaud sur un serveur et que vous souhaitiez malgré tout travailler dessus lorsque
vous serrez en voyage. Dans ce cas 2 solutions s'ouvrent à vous :
#. Utiliser un logiciel de synchronisation des données comme RSync ou FreeFile Sync. Vous
devrez être vigilant, lors des synchronisations, que les données sont bien
synchronisée dans le bon sens.
#. Utiliser une solution de stockage dans le Cloud comme *OneDrive*, *DropBox* ou
*Google Drive*. Ces trois services proposent des solutions gratuites ou payantes. La
principale différence entre les offres gratuites et payantes est, la plupart du
temps, l'espace mis à votre disposition.
Si vous le pouvez, privilégiez la seconde solution car le travail est effectué
automatiquement en tache de fond et vous aurez en plus des possibilités de sauvegarde et de
restauration.
* **Publication sur un dépôt distant** :
La gestion publique est toujours compliquée, car par principe on publie la version stable, même
si cette version n'a pas toutes les fonctionnalités. Une version stable est une version
fonctionnelle et n'ayant pas de problèmes bloquants.
L'utilisation de GIT et d'un gestionnaire de dépôt distant comme Github ou Gitlab permet de
s'affranchir de cette gestion des versions puisque comme indiqué dans
`Versionner tout un projet `_ on travaille avec la notion de branche.
Il faut envisager GIT comme un arbre. Avec la branche Master pour le tronc et toutes vos
autres branches (Dev, gh-pages, test_fonction_truc, etc.) comme un branchage avec les
différentes ramifications.
**N.B** : Certains outils de gestion de projet ou certains IDE permettent nativement de
"pousser" vos fichiers directement sur les dépôts distants.
Commenter et Documenter son code
--------------------------------
:Liens_Web:
* https://fr.wikipedia.org/wiki/G%C3%A9n%C3%A9rateur_de_documentation
# Page d'explication et de démonstration des générateurs de code
Que vous soyez grand débutant ou un baroudeur tout terrain en programmation, vous allez forcément
vous retrouvez devant la double problématique :
*"Elle fait quoi cette saleté de méthode ?!"*
et
*"Comment je vais faire pour documenter tout ce Bazar ?"*
Pour la première question, la réponse est qu'il faut absolument mettre des commentaires dans votre
code, ça vous aidera à mieux comprendre votre programme après une pause (plus ou moins longue) dans
vos travaux. Souvenez-vous du : "`Pour qui et pourquoi `_" évoqué plus haut.
Pour la deuxième question, il faudrait pouvoir reprendre chacune des Classes et Méthodes qui compose
votre code pour pouvoir en faire une description complète et donc permettre à n'importe qui (vous
par exemple) d'utiliser votre programme ou l'interface de programmation de votre application (`API `_).
La thématique de ces deux questions, et la même. Il faudrait donc trouver une solution pour que les
commentaires qu'on met dans du code soit automatiquement utilisés pour générer la documentation.
Heureusement, cette solution existe sous la forme de logiciels qui interprète les commentaires de
votre code pour générer une documentation souvent disponible dans plusieurs format (html, PDF, EPUB).
Ces Logiciels se nomment des **Générateur de documentation** voir le lien Web ci-dessus.
Il en existe plusieurs (quasiment 1 par langage) à vous de trouver votre bonheur. Voici un
échantillon :
* `Sphinx `_ : pour Python
* `Javadoc `_ : pour Java
* `Doxygen `_ : multi langage, mais principalement pour
le C / C++
Les commentaires insérés dans le code doivent respecter une certaine syntaxe (différente en fonction
de l'outil utiliser).
Le document généré peut être utilisé et intégré dans votre propre documentation.
.. image:: ./Images/Deco/ampoule.png
:width: 50px
:height: 50px
:align: left
:Petites Astuces:
#. Les générateurs de documentation étant capable de générer du html, vous
pouvez faire en sorte que ces documents soient directement publier sur
Github.io ou ReadTheDoc.
Il est même possible de gérer toute la documentation d'un projet avec ce
genre de programme. C'est le cas pour tous mes projets (dont le présent
document) pour lesquels j'utilise **Sphinx** (Générateur de documentation),
**ReStructuredText** (Langage de balisage léger) et **Github.io** (support de
publication en ligne).
#. Lorsque vous modifiez votre code, pensez à modifier les commentaires
également car lorsque vous reprendrez votre code, il y a de grandes chances que
vous ne lisiez que les commentaires.
Ne pas négliger la sécurité
---------------------------
**Il ne faut jamais laisser des informations personnelles dans vos documentations, dépôts ou code !**
Les identifiants et mots de passe, les codes bancaires, adresses et numéros de téléphones, clefs privées
de chiffrement, sont autant d'informations que vous ne devez en aucun cas diffuser.
Si dans l'un de vos codes vous avez besoin de renseigner ce genre d'informations il faut les placer
dans un dossier séparer (par exemple 'Creds' ou 'Credential') et vous assurer que seul votre code
(en local) peut accéder à ce dossier et qu'il ne sera pas pousser avec le reste du projet sur les
réseaux. GIT vous permet de d'ignorer les éléments qui sont renseigner dans le fichier '.gitignore'
Vous devez donc ajouter '\*/Creds/\*' dans ce fichier, si votre dossier se nomme 'Creds', pour qu'il
ne soit pas pris en compte dans la gestion du projet.
Demander de l'aide de temps en temps
====================================
De la même façon qu'il est difficile de mener un projet entièrement seul, il peut être intéressant de
demander l'aide d'une ou plusieurs personnes pour faire une documentation.
La première chose que je vous conseille de demander, si vous trouvez une personne de bonne volonté,
c'est de demander que quelqu'un relise votre doc. Vous aurez ainsi un avis objectif sur ce qui
est bien, ce qui ne l'est pas et sur les choses incompréhensibles qu'il sera bon de clarifier.
La seconde chose à demander, peut être que l'on vous aide à la prise en main de certains outils qui,
si on n’en a pas l'habitude, peuvent être difficile à maitriser. Ces outils sont certainement utilisés
dans les Fablabs ou les Hackerspaces. N'hésitez pas à vous y rendre pour trouver de l'aide.
Les outils et médias de diffusions
==================================
Comme pour tous travaux, il y a toujours plusieurs façons de les réaliser. En fonction de ce que
l'on veut faire il faut utiliser le bon outil. La difficulté étant de savoir quels sont les outils
qui existe et ce qu'ils font.
Voici donc les quelques outils que j'utilise. Il en existe d'autre, ce sera à vous de les découvrir
et de vous les approprier.
Les outils de dessin
--------------------
Il est toujours intéressant de pouvoir ajouter un croquis ou une image pour permettre d'illustrer
un point particulier.
* `Inkscape `_ est un logiciel de dessin vectoriel. Ce
logiciel Open-source permet de créer facilement de croquis, des schémas ou des images.
On peut trouver facilement des tutos en faisant une recherche : `Inkscape tuto `_
* `GIMP `_ est un logiciel de traitement d'image Bitmap. Ce logiciel
Open-source permet de manipuler des images de la même façon que Photoshop d'Adobe.
De nombreux tutos sont disponible : `Gimp tuto `_
* `XnView `_ est un logiciel Open-source de traitement d'image par
lot. Il vous permet de redimensionner, de convertir ou renommer vos images par lot
Les outils de production
------------------------
* `Fusion 360 `_: Il s'agit d'un logiciel
de modélisation 3D de design industriel. Bien qu'étant un produit Autodesk (donc close source),
il est gratuit pour les hobbyistes, les étudiants, les enthousiastes et les entrepreneurs
réalisant un chiffre d'affaire de moins de 100 K$ par ans.
La communauté est très active et il y a une `chaine dédiée sur YouTube `_
qui propose énormément de tutos.
* `Kicad `_ : Permet d'éditer des schémas électroniques, router des PCB,
générer les typons et gérer le fichier de perçage. Ce logiciel open source à une
forte communauté, ce qui permet de trouver de l'aide facilement.
* Un éditeur de texte : Je préfère travailler avec des éditeurs de texte simple permettant la
coloration syntaxique, la numération automatique des lignes et l'édition de code.
J'utilise `VIM `_ par ce qu'il est disponible sur toutes les
plateformes (Windows, MacOs, Linux, BSD). C'est un outil un peu compliqué à utiliser car il
pour l'utiliser il faut tout apprendre depuis le début. Même une tâche aussi simple qu'un
copier / coller est compliqué.
Si vous êtes sous Windows, vous pouvez utiliser `Notepad ++ `_
qui fera très bien le boulot.
Si vous ne faites pas de code et que vous préférez le confort d'un éditeur de texte `WYSIWIG `_
comme `Word `_ ou `Libre Office `_,
cela ne pose aucun problème. Souvenez-vous simplement que ce genre de soft peut parfois vous
réserver des surprises au niveau du formatage du texte lorsque vous l'exporterez vers un WIKI.
* Logiciel de gestion de version
* `GIT `_ : Permet une gestion de version décentralisée (qui n'a pas
besoin d'un serveur) c'est l'outil ultime du développeur. Il permet de garder une version
stable et de tester ou de développer en parallèle sans remettre en question le bon
fonctionnement de la branche stable. GIT permettant la gestion de version de fichier texte,
vous pouvez l'utiliser pour gérer tous vos projets dont les éléments de construction
génèrent des fichiers texte. (txt, xml, html, python, C Plus Plus, INI, etc.
* `Tortoise `_ : Ce programme s'interface entre GIT et vous. Il
s'intègre dans votre explorateur et vous permet de gérer toutes vos manipulations GIT à
partir de votre souris, ce qui représente un sérieux atout pour tous les allergiques à la
ligne de commande. Il ajoute en plus un indicateur visuel à vos fichiers pour que vous
puissiez identifier les éléments qui ont été modifiés récemment et qui n'ont pas encore été
versionnés
* Autres : Il existe d'autre logiciel de versioning, comme Mercurial ou SVN. A vous de les
découvrir et de choisir votre outil préféré.
Les outils de traduction des textes
-----------------------------------
Que ce soit dans la préparation ou dans la réalisation de votre projet, vous allez certainement
devoir consulter des sites ou des docs écris dans une autre langue. Cela peut vite être très
handicapant. Voici deux outils qui permettent de traduire : un mot, un texte, un document ou un site.
* `Google Translate `_ : Il s'agit de l'outil de Google que tous
le monde connait.
* `Deepl `_ : Il s'agit d'un outil de traduction qui amène
plus de nuance dans les traductions et qui génères des traductions de meilleur qualité que ces
concurrent.
Les langages de balisage en texte clair (Plantext Markup Language)
------------------------------------------------------------------
Les langages de balisages en texte clair sont des langages qui doivent pouvoir être interprété
informatiquement tout en en restant parfaitement lisible par les humains. Cela permet d'écrire
un document sans avoir à se préoccuper de l'aspect esthétique. Seule une syntaxe peu contraignante
est à respecter pour que le document puisse être interpréter par l'ordinateur.
:Liens_Web:
* https://fr.wikipedia.org/wiki/Langage_de_balisage_l%C3%A9ger
# Petite explication sur les langages de balisage simples
* https://fr.wikipedia.org/wiki/LaTeX
# Page Wiki de présentation du LaTeX
* `reStructuredText `_
et `Markdown `_ : Ces langages sont
utilisés nativement par Github, ReadTheDoc et GitLab. Sphinx s'appuie sur le reStrucredText.
* `LaTeX `_ : il s'agit d'un langage permettant
la création de document très élaboré. Il est très utilisé par la communauté scientifique pour
ses possibilités d'écriture de systèmes mathématiques. Il est également de plus en plus
utilisé dans la presse pour ses possibilités de gestion des mises en page.
**Attention** Il s'agit d'un outil très puissant mais très compliqué à utiliser et à
mettre en œuvre.
* `MediaWiki `_ et `DokuWiki `_ :
Il y a actuellement deux types de moteur WIKI. Chacune utilisant une syntaxe différente.
Les générateurs de documentation
--------------------------------
:Liens_Web:
* https://fr.wikipedia.org/wiki/G%C3%A9n%C3%A9rateur_de_documentation
# Page WIKI sur les générateurs de documentation
Les générateurs de documentation (`voir Commenter et Documenter son code `_)
permettent de récupérer les commentaires et balises que vous intégrez dans votre code pour générer
une documentation. Cette documentation peut être générée sous différents formats. Pour une
publication sur le WEB, c'est le format **html** qui est le plus pratique.
Il en existe dans tous les langages, par exemples :
* `Sphinx (pour Python) `_
* `Javadoc (pour Java) `_
* `Doxygen (pour le C/C++) `_
Cette documentation extraite de votre code améliore la qualité de votre projet tout en vous permettant
une lecture plus confortable de votre interface.
Les outils de publication des projets et de la documentation
------------------------------------------------------------
:Liens_Web:
* https://fr.wikipedia.org/wiki/Wiki
# Page de définition d'un WIKI
Il y a plusieurs moyens à votre disposition pour publier vos projets et vos documentations sans
obligatoirement devoir faire appel à un éditeur ou à un service marketing
* Les Wiki (`moteur MediaWiki `_ et `moteur DokuWiki `_) :
Les Wikis, dont le plus connu est certainement Wikipédia sont des espaces de publication et
d'information collaboratifs, c'est à dire que ce que vous y écrivez peut-être
modifié / corrigé / complété par d'autres personnes. Ils représentent une très bonne
solution pour la présentation et la documentation des projets. En particulier si le projet a
été réalisé dans le cadre d'un travail universitaire, d'un fablab ou de n'importe quel espace
collaboratif.
* Les gestionnaires de dépôt distant (`Github `_, `Read The Docs `_, `GitLab `_) :
GitHub et Gitlab permettent
tous les deux de partager des projets et leur documentation. Ils offrent tous les deux la
possibilité de créer une page Wiki spécifique à votre projet. Seul Github propose de générer
une page web regroupant toute votre documentation. ReadTheDoc ne permet que de créer une page
web. C'est un bon complément à GitLab.
* Les sites de partage de projet en mode DIY (Faites le vous-même) : Ce sont des plateformes
qui permettent de présenter des projets sous la forme d'un tutoriel pas à pas. Pour vous faire
une idée, vous pouvez visitez les trois exemples ci-dessous :
* `Oui Are Makers `_
* `hackster.io `_
* `Instructables `_
####
----------------------------------------
Avant, pendant et après la documentation
----------------------------------------
:Avant: Vous devez vous créer une structure de travail, rassembler les différentes
documentations que vous avez déjà et définir les objectifs de votre projet.
Ces éléments vous serviront à la fois : à la réalisation de votre projet et à
l'établissement de votre documentation.
.. image:: ./Images/Deco/ampoule.png
:width: 50px
:height: 50px
:align: left
:Petites Astuces:
#. La création d'une fiche projet vous permettra non seulement de
définir les objectifs de votre projet mais en plus, cela vous
permettra de synthétiser vos idées.
Lorsque vous aurez défini les objectifs de votre projet, identifiez
pour chacun d'entre eux les taches et actions qui le composent. Cela
vous permettra d'avoir un ensemble de petits objectifs permettant de
simplifier le processus global de création.
Ces sous-objectifs peuvent être intégrés dans la fiche projet et
font partie intégrante de la documentation.
:Pendant: #. Essayez d'écrire votre documentation en parallèle du développement de votre
projet. Puisque le travail de rédaction prend toujours beaucoup de temps, il y a
de grandes chances que vous soyez souvent amené à vous interrompre en cours
d'écriture. Vous devez vous laisser des informations vous signalant qu'un
paragraphe n'est pas encore terminé. Pour ma part, j'entoure les éléments en
cours de rédaction (ou pour lesquels une modification est à effectuer) par deux blocs
'[WIP]' (Work In Progress : Travail en cours). Ces blocs sont supprimés quand la
partie en cours est complète ::
Ex:
[WIP]
Un bout de doc vachement bien mais encore incomplet ...
[WIP]
Cela vous permet d'avoir immédiatement une information visuelle sur ce qui est
complet.
**N.B** : Même si vous avez supprimé ces blocs, vous pouvez faire des modifs ou
autres améliorations sur les paragraphes déjà traiter. Pensez juste à vous laisser
des indices si vous effectuez une refonte du paragraphe ou si vous y ajoutez un
complément conséquent.
#. Une autre petite astuce est d'insérer des penses bêtes dans vos documents pour
que vous vous rappeliez que vous vouliez parler d'un truc. Je mets ces penses bêtes
dans les fichiers "Bug_ToDo_lst" (qu'il faut consulter régulièrement). Cependant,
dans le feu de l'action, il m'arrive
de les mettre directement dans mon document. Pour les identifier, je les
entoures encore une fois par 2 blocs : [TODO] (à faire) ::
Ex:
[TODO]
Parler des trucs super important que j'oublie tout le temps
[TODO]
Ou:
[TODO]
Mettre la rubrique machin avant le paragraphe bidule-truc
[TODO]
#. Essayez d'avoir une construction logique dans votre document. Il faut que votre
document soit facile à lire. Pour cela, il faut éviter de renvoyer le lecteur
vers une autre partie du texte avant de revenir sur la partie actuelle.
#. Pour vous aider à naviguer facilement dans votre documentation, insérez une
**Table de matières** dans votre documentation. Il est à noter que les outils de
publication WEB (WIKI, Sphinx, etc.) ajoutent automatiquement cette table des
matières.
Si votre documentation n'est pas dynamique (PDF, papier, etc.), pensez
à ajouter les numéros de pages en face de chaque rubrique. Les logiciels de
traitement de textes (Word, Libre Office, etc.) sont capables de générer cette
table des matières en ajustant automatiquement les numéros de pages.
Pour que les logiciels fassent une partie du travail à votre place, il faut leur
préparer le travail. Dans le cas des tables des matières, il faut utiliser le
balisage des titres présent dans ces logiciels.
**N. B.** : Pour les WIKI ou pour Sphinx, les titres sont définis par des
conventions syntaxiques.
#. N'oubliez pas de vous relire (souvent) pour vous assurer qu'il n'y a pas de
doublon, de non-sen, d'incohérence ou simplement de coquille dans votre doc.
#. Définissez votre projet et tenez-vous y. Il est possible voir fréquent qu’un
projet évolue en cours de route. Tant que vous ne cherchez pas à le faire évoluer en
permanence. Essayez d'aller au bout du projet sous la forme que vous avez défini et
par la suite, faites une nouvelle version du projet qui elle aussi sera défini selon
des objectifs précis (ou à peu près). C'est la seule façon de pourvoir finir un
projet et cela aide à ne pas se décourager (voir à abandonner) en cours de route.
:Après: Relisez votre document, faites-le relire par quelqu'un d'autre et lorsque tout
semble correcte, essayez d'agrémenter un peu votre document. C'est particulièrement
important si votre document est exclusivement textuel. Voir `Les finitions`_.
####
------------
Les licences
------------
Il est important que vous attribuiez une licence à vos travaux. La documentation ne fait pas
exception.
Par défaut, si vous ne définissez pas explicitement une licence pour vos projets ou vos
documentations, c'est le `Copyright `_ (appelé
"`Droit d'auteur `_"
en France) qui s'applique par défaut sur vos œuvres et créations. Dans ce cas une personne tiers ne
pourra consulter et utiliser vos créations que dans les conditions de mise à disposition de l'œuvre
que vous aurez défini.
Si votre projet n'a pas vocation à être 'libre' ou open sources, assurez-vous d'en avoir bien
définit la paternité en la signant avec votre nom ou un pseudonyme (à condition que ce dernier ne
soit pas lui aussi utilisé par une tierce personne).
Si vous souhaitez mettre votre création à disposition de tout le monde et permettre à quiconque de
la modifier et de la redistribuer selon ses propres conditions, il faut utiliser la
`licence X11 (licence MIT) `_.
Vous pouvez consulter les différentes licences depuis les liens Web ci-dessous :
* `Liste des licences `_
Pour ma part, j'utilise systématiquement la licence :
`CC BY-NC-SA `_.
.. image:: ./Images/CC/cc-by-nc-sa_88x31.png
:align: center
:name: CC-BY-NC-SA
:alt: CC-BY-NC-SA
:target: https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode
Cette licence définit les termes suivants :
* **BY** : l'attribution. En cas d'utilisation ou de modification, l'auteur doit être cité
* **NC** : Pas d'utilisation commerciale. Une tierce personne ne peut pas vendre tout ou partie du
projet ou de la documentation qui lui est rattaché.
* **SA** : Partage dans les mêmes conditions. Même si quelqu'un modifie le projet, il ne peut pas
s'attribuer la paternité du projet ni changer le type de licence.
Je place cette licence systématiquement dans les fichiers 'README.RST' présent dans tous mes projets.
####
-------------
Les finitions
-------------
Lorsque vous aurez enfin tout fini. Vous pourrez passer aux petits détails de dernières minutes,
comme la décoration ou la publication de la doc et du projet.
Agrémenter sa documentation
===========================
Lorsque vous aurez terminé votre documentation, vous allez certainement vous trouver face à un bloc
de texte monolithique. Pour rendre votre documentation plus attractive il vous suffit d'ajouter
quelques images et / ou dessins.
Vous ne pouvez pas utiliser la première photo de chatons venus car vous ne le savez peut-être pas
mais la plupart des photos que l'on trouve sur internet ne sont pas libre de droits. Vous n'avez
donc pas les droits de les utiliser.
Pour trouver des images libres de droits, il vous suffit de faire la recherche suivante : ::
# Recherche avec mots clefs en Français
image domaine public gratuit
# ou encore
illustration domaine public
# Recherche avec mots clefs en Anglais
public domain pictures
# Recherche de dessins vectorisés et clipart
public domain vector
Publier sa documentation et son projet
======================================
La publication de votre documentation doit être envisagée dès le début de votre projet car les
outils de rédactions sont différents selon que vous souhaitiez publier sur un WIKI, sur Github ou
dans une revue scientifique.
**N. B.**: En plus des outils, la syntaxe des langages utilisés est également très différentes.
Les pièges à éviter
-------------------
Même si cela parait être une façon simple et efficace de publier sa documentation, **il ne faut
jamais la publier dans un blog ou un forum**.
* **Les blogs** : Un blog doit uniquement servir de vitrine. On peut y faire un article
présentant son projet avec quelques photos et des liens qui pointent vers le dépôt et vers
sa documentation.
* **Les forums** : Les forums représentent un lieu de partage et d'entre aide. Les posts qu'on y
met permettent de publier quelques photos de l'évolution d'un projet, de donner ou de recevoir
de l'aide, de présenter le projet fini ou de mettre une jolie photo avec des liens vers le
dépôt et vers sa documentation.
La raison pour laquelle il ne faut pas publier un projet ou une documentation sur un forum ou un
blog est simple. Sur ces médias, seuls les derniers articles sont affichés. Il faut alors savoir
exactement ce qu'on cherche pour pouvoir retrouver un article précis. De plus, il est compliqué de
devoir rééditer un article chaque fois qu'on veut faire évoluer la documentation. C'est même encore
pire sur les forums car on risque d'avoir une suite dissolue d'éléments qu'il sera compliqué de réunir
pour avoir une vision globale du projet.
####
-----------
Conclusions
-----------
Vous devriez maintenant avoir suffisamment d'informations pour pouvoir faire votre propre
documentation.
Je vous conseille de faire ce travail de documentation car au-delà de vous aider en cas de reprise
d'un projet, le travail de documentation vous aidera à fournir un meilleur travail sur votre projet.
N'hésitez pas à vous rendre dans un FabLab (VoLAB ?!) pour trouver de l'aide vous permettant d'aller
au bout de vos projets.