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 |
|---|
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.
Il y a deux thèmes importants dans la documentation :
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.
Que faut-il mettre dans la documentation ?
A cette question ma réponse est : Tous ce que vous pouvez !
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 :
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.
| 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 |
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.
| 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. |
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 :
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.
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.
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 :
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
| 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. |
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.
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.
Lorsqu’on travaille sur un projet, on peut être amené à manipuler de nombreux éléments différents comme :
Pour gérer ces documents, vous avez plusieurs solutions :
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 :
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.
| 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. |
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 :
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 :
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.
| 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).
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
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.
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.
| 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 :
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.
| 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. |
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.
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.
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.
Il est toujours intéressant de pouvoir ajouter un croquis ou une image pour permettre d’illustrer un point particulier.
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.
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 |
|---|
| 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 :
Cette documentation extraite de votre code améliore la qualité de votre projet tout en vous permettant une lecture plus confortable de votre interface.
| 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
| 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. 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. |
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 :
Pour ma part, j’utilise systématiquement la licence :
Cette licence définit les termes suivants :
Je place cette licence systématiquement dans les fichiers “README.RST” présent dans tous mes projets.
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.
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
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.
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.
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.
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.
Debian : Installer un serveur DHCP Outils Historique Version imprimable Table des matières INTRODUCTIONINSTALLATION DE DHCPCONFIGURATION…
I. Présentation Le service DHCP est très répandu dans les entreprises afin de distribuer une…
Préalables pour le lecteur : pour tirer le maximum de profit de la lecture de cet…
Imagemagick Imagemagick est un logiciel ultra-puissant qui s'utilise en ligne de commande et qui permet de…
Mesures de sécurité essentielles à WordPress 1- Le compte Admin En premier lieu, quelque soit…
Activer le mode maintenance sur WordPress Le mode de maintenance de WordPress est activable par…