ceux qui lisent pas la doc, sont aussi ceux qui ne l’écrivent pas ceci dit en passant...
C'est marrant ça. Parce que moi, quand j'écrivait de la doc (tout le temps quand j'était au taf, a divers niveaux de qualité en fonction de l'urgence et de la finition) c'était pour tout le monde, les autres, et moi.
Je préfère avoir une doc qui me permette de revenir 3 mois plus tard a un code que j'ai oublié parce qu'entre temps je suis passé sur 2 ou 3 autres sections du système, et très honnêtement, je sais pertinemment que pour de la doc, mieux vaut ne pas attendre après les autres...
Donc, si tu veux de la doc utile, c'est pas compliqué: tu te sors les doigts quand tu fais ton projet, tu commences par documenter l'archi du proto, puis tu code, puis tu mets à jour la doc. C'est p'tet pas agile, c'est pas non du plus du V, mais ça a très bien marché pour moi. Et quand un collègue venait me sortir qu'il avait trouvé un bug dans mon code, je demandais 2 choses: les logs, et 5 minutes pour qu'il me dise pourquoi il avais mal interprété la doc. Que je la mette à jour.
Alors, quand je parle de doc, hein, je parle pas de ces horreurs de fichiers word. Je parle d'un simple .txt posé dans le repo, et quand ça deviens trop massif, je le divise (typiquement: utilisation, déploiement et maintenance, déjà ça rend les choses plus simples).
Oui c'est moche le .txt, y'a pas de couleurs, pas de gras... mais on peut faire des paragraphes et des retours à la ligne sans se prendre la tête, on peut utiliser son éditeur de code préféré pour maintenir/visualiser, et ça se versionne super bien. Tant qu'on ne s'amuse pas trop a coller des URI à rallonge en brut dans le texte, mais ça de toute façon on peut pas y faire grand chose (enfin si: les mettre dans un index, mais de toute façon c'est rare que je colle des URIs longues dans une doc technique).
[^] # Re: Maintenance
Posté par freem . En réponse au journal La cochonnerie en boite que sont les systèmes de dépendances. Évalué à 3.
C'est marrant ça. Parce que moi, quand j'écrivait de la doc (tout le temps quand j'était au taf, a divers niveaux de qualité en fonction de l'urgence et de la finition) c'était pour tout le monde, les autres, et moi.
Je préfère avoir une doc qui me permette de revenir 3 mois plus tard a un code que j'ai oublié parce qu'entre temps je suis passé sur 2 ou 3 autres sections du système, et très honnêtement, je sais pertinemment que pour de la doc, mieux vaut ne pas attendre après les autres...
Donc, si tu veux de la doc utile, c'est pas compliqué: tu te sors les doigts quand tu fais ton projet, tu commences par documenter l'archi du proto, puis tu code, puis tu mets à jour la doc. C'est p'tet pas agile, c'est pas non du plus du V, mais ça a très bien marché pour moi. Et quand un collègue venait me sortir qu'il avait trouvé un bug dans mon code, je demandais 2 choses: les logs, et 5 minutes pour qu'il me dise pourquoi il avais mal interprété la doc. Que je la mette à jour.
Alors, quand je parle de doc, hein, je parle pas de ces horreurs de fichiers word. Je parle d'un simple .txt posé dans le repo, et quand ça deviens trop massif, je le divise (typiquement: utilisation, déploiement et maintenance, déjà ça rend les choses plus simples).
Oui c'est moche le .txt, y'a pas de couleurs, pas de gras... mais on peut faire des paragraphes et des retours à la ligne sans se prendre la tête, on peut utiliser son éditeur de code préféré pour maintenir/visualiser, et ça se versionne super bien. Tant qu'on ne s'amuse pas trop a coller des URI à rallonge en brut dans le texte, mais ça de toute façon on peut pas y faire grand chose (enfin si: les mettre dans un index, mais de toute façon c'est rare que je colle des URIs longues dans une doc technique).