Bonjour,
Je développe essentiellement en PHP/HTML/Javascript/SQL, je me suis lancé dans l'écriture de documentation technique de mes développements au moyen de LyX.
J'aime beaucoup ce genre d'outil qui permet de se concentrer sur le contenu (sans s'occuper de la mise en forme, ni avoir à apprendre un nouveau langage ;-) et après quelques recherches sur le nain ternet, j'aimerai recueillir vos conseils éclairés :
confirmez-vous que ce choix est un des plus adaptés pour cette tache ?
actuellement j'utilise la classe de document Report, existe-t-il un layout spécifique pour présenter ce genre de doc (pas d'équations mathématiques/physique, mais des bouts de code, des tables et instruction SQL, copies d'écrans, des diagrammes UML) ?
des tutoriels (même en vidéo) qui soient orientés documentation d'application informatique ?
# Documentation technique au format texte ?
Posté par lerouquin . Évalué à 3.
Ancien adepte de LaTeX, dans le cas d'une documentation technique, aujourd'hui mon choix se porterait plutôt sur reStructuredText ou markdown.
Ce sont des fichiers textes qui suivent quelques conventions de mise en forme simples (comme celles utilisées pour rédiger cette réponse) qui ont le double avantage d'être faciles à écrire dans n'importe quel éditeur capable de produire du texte, et surtout d'être lisibles tel quel sans que le balisage n'entrave réellement la lecture.
Ensuite, avec un outil tel que Pandoc, il est possible de transformer ces bêtes fichiers textes en tout et n'importe quoi (LaTeX, ePub, pages de man, ou même docx pour peu qu'un client en exprime le besoin…).
Ou encore, grâce à Sphinx pour reStructuredText ou MkDocs pour markdown, un simple fichier de configuration permet de générer aisément de très belles pages statiques pouvant être hébergées n'importe où et ainsi rendues accessible aux moteurs de recherches.
Par ailleurs, les fichiers de documentations peuvent être directement versionnés avec le projet et les commandes pour générer et publier la documentation peuvent être intégrées à la compilation et/ou au déploiement.
Autre exemple de la versatilité de cette solution : une plate-forme comme ReadTheDocs utilise des webhooks pour qu'à chaque commit du projet sur un dépôt public comme GitHub ou BitBucket, les docs sont extraites, générées avec Sphinx/MkDocs et directement publiées.
[^] # Re: Documentation technique au format texte ?
Posté par tetraf . Évalué à 1.
Pour de la documentation (et d'autres choses), il y a aussi AsciiDoc qui a l'avantage d'être assez complet et, accessoirement, d'avoir une syntaxe plus agréable que Markdown :-)
[^] # Re: Documentation technique au format texte ?
Posté par Olivier LEMAIRE (site web personnel) . Évalué à 1.
Bonjour à tous,
au risque de dire une bêtise, on peut documenter son code avec doxygen. Ca marche plutôt bien, le résultat est pas mal voire bon et c'est libre. je sais pas si ca marche bien pour tous les langages mais en tout cas, la page de doxygen dit que ca marche pour PHP. Moi ce que j'aime bien dans doxygen c'est que ça sort du html et/ou du Latex…
Je ne sais pas à qui s'adresse ta doc mais voici un exemple de ce qu'on peut faire avec : http://qwt.sourceforge.net/
Les logiciels de traitement de texte sont à la rédaction ce que la 2CV est à l'automobile, une vieille voiture dont on se souvient avec nostalgie mais technologiquement dépassée
[^] # Re: Documentation technique au format texte ?
Posté par pralines . Évalué à 1.
merci à tous pour ces informations
cette doc ne va pas contenir uniquement la liste des fonctions et leurs paramètres, donc doxygen est utile mais pas suffisant
je voulais faire mélange de texte, bout de code, copies d'écran, je réalise que ça ne va pas être si simple d'écrire 1 seul document avec Lyx (surtout du fait des nombreuses copies d'écran et de leur positionnement dans le document dont la logique m'échappe),
je vais sans douter être obligé de personnaliser la classe de document et donc apprendre à parler la même langue que Lyx (ce que j'avais espéré éviter avec un outil quasi-wysiwyg…)
Envoyé depuis mon Archlinux
[^] # Re: Documentation technique au format texte ?
Posté par Olivier LEMAIRE (site web personnel) . Évalué à 1.
Lyx, c'est jamais que du latex et pour le latex il y a une source qui pourrait te donner de bonnes pistes pour apprendre :
http://framabook.org/5-tout-ce-que-vous-avez-toujours-voulu-savoir-sur-latex-sans-jamais-oser-le-demander/
C'est pas la meilleure source de toute l'histoire du latex mais elle a le mérite d’être en français, plutôt claire, téléchargeable ou achetable, le tout sous licence libre…
Latex c'est un peu étrange au début mais rapidement on voit toute la puissance du système. Pour les figures, le placement, on s'en fout un peu. Ce qu'il faut c'est faire des \label et des \ref; c'est bien expliqué dans le bouquin.
Il ne faut pas hésiter à venir demander de l'aide sur les canaux irc (#latex sur freenode.net—osfe). Si tu as besoin d'aide n'hésite pas à venir me demander sur le canal, j'y suis tout le temps.
J'ai aussi fait un modèle de document en latex si tu veux y jeter un oeil : https://github.com/osfe/bash_scripts/tree/master/mklatex
Olivier
Les logiciels de traitement de texte sont à la rédaction ce que la 2CV est à l'automobile, une vieille voiture dont on se souvient avec nostalgie mais technologiquement dépassée
[^] # Re: Documentation technique au format texte ?
Posté par pralines . Évalué à 1.
c'est super sympa, merci pour la proposition d'aide (et pour la lecture)
contrairement à ce que j'ai pu laisser penser, je n'ai jamais cherché à écrire en Latex et je me rend compte que ce que je voulais, c'est un éditeur qui s'occupe en priorité de la structure du contenu
Lyx génère du Latex de façon graphique (pas besoin d'apprendre le langage, mais quand le besoin s'en fait sentir on peut saisir du code Latex),
ce qu'on saisi, c'est le texte en fançais et on n'est pas "distrait" par toutes les instructions Latex au milieu de son texte
un truc que je n'ai vu que dans LYX : on peut intervenir sur la table des matière et ainsi changer l'ordre des sections, le contenu des chapitres est déplacé d'un simple clic souris (monter/descendre un chapitre/section)
comme je n'ai rencontré cette dernière fonctionnalité dans aucun autre produit, je vais persister quelque temps dans LYX et mon principal souci va être de personnaliser la présentation (marges, position et dimensionnement des grandes images pour qu'elles ne dépassent pas de la page…)
Envoyé depuis mon Archlinux
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.