Rédaction technique
Blog Un blog consacré à tout ce qui touche à la documentation gérée comme du code.
Insérer automatiquement des données dans un fichier DITA XML Nous voulons automatiser la génération du fichier DITA suivant :
Base de données SQL Dans le cas d'un CMS (Content Management System) de type Drupal, Joomla ou WordPress, le référentiel est une base de données SQL.
Collecte de l'information Le rédacteur technique collecte l'information auprès de différentes sources, internes et externes à l'entreprise.
Création du contenu Le rédacteur technique crée le contenu du projet de rédaction technique dans un dialogue constant avec les différents acteurs de la société : services R&D, marketing.
Définition du projet Communiquer des informations techniques sans savoir à qui ni dans quel but est un effort vain.
Format cible Le format cible d'un support de rédaction technique est celui sous lequel l'audience du message y accédera.
Format source Les traitements de texte nous ont déshabitués à distinguer le fond de la forme. Mais confondre les deux entraîne beaucoup d'erreurs et de perte de temps.
Git : du fichier au contenu Sous Git, pensez contenu plutôt que fichiers : c’est plus simple et évite bien des difficultés.
Intégrer la documentation aux processus de développement La documentation fait partie du logiciel.
Les CMS : le workflow en prime, mais une fiabilité à tester S’ils utilisent des formats monolithiques tels que FrameMaker, les rédacteurs techniques peuvent utiliser des CMS tels que SharePoint, Alfresco ou consorts.
Les répertoires réseau partagés - peu adaptés au travail de groupe Les fichiers partagés par une équipe de rédaction technique sont souvent stockés dans un répertoire partagé sur le réseau.
Les systèmes de gestion de versions - rustiques mais fiables Gérer la documentation texte avec un système de gestion de versions (Git, Subversion, SourceSafe) comme le code.
Livraison Le rédacteur technique livre le document à son destinataire de la manière appropriée.
Quel référentiel pour le travail de groupe ? Pour travailler sur un fichier, le rédacteur technique utilise un programme qui lit le fichier sur son disque dur et en charge une copie en mémoire vive.
Référentiel Le contenu est le capital immatériel de la société et doit être protégé comme tel.
Tester les produits pour les documenter Un conte chinois narre comment des aveugles se sont retrouvés confrontés à un éléphant.
Traduction Les contraintes de traduction doivent être prises en compte en amont du processus rédactionnel.
Un référentiel unique ? Idéalement, tout le contenu peut être placé sous un référentiel unique (par ex. Git) pour maximiser réutilisation, cohérence et qualité.
Utiliser les branches des systèmes de gestion de sources Créer des branches dans un gestionnaire de sources pour gérer des projets divergents et les traductions de la documentation.
Validation et contrôle qualité Le contenu doit être validé avant livraison.
De la rédaction à la communication technique La communication technique est souvent réduite à la rédaction technique. La rédaction technique est destinée à fournir la documentation des produits, et intervient en aval de la vente.
Formats et outils Lorsqu’une entreprise industrialise la rédaction technique, la question clé n’est pas l’outil mais le format sous-jacent.
Les trois niveaux de la documentation technique Si l’on compare la documentation technique à un jardin, on peut la classifier selon les niveaux suivants :
Principe de simplicité KISS Le principe KISS (Keep it simple stupid) est un principe général d’ingénierie qui préconise la simplicité pour améliorer fiabilité, maintenance et évolutivité.
Un index est-il utile dans un PDF ? La recherche en plein texte semble avoir détrôné l'index.
Cas concret : documentation de NuFirewall La documentation de NuFirewall, qui a été perçue par la presse comme un point fort du produit, a été réalisée sous DITA XML.
Cas concret : documentation de NuFirewall La documentation de NuFirewall, qui a été perçue par la presse comme un point fort du produit, a été réalisée sous DITA XML.
Cas concrets d'utilisation de DITA XML L'utilisation quotidienne du format de rédaction structurée DITA XML sur des projets multilingues en tant que rédacteur technique m'a amené à développer certaines solutions et astuces que je vous livre ici.
Cas concrets d'utilisation de DITA XML L'utilisation quotidienne du format de rédaction structurée DITA XML sur des projets multilingues en tant que rédacteur technique m'a amené à développer certaines solutions et astuces que je vous livre ici.
Du document à la base documentaire modulaire Le format de rédaction structurée DITA XML propose de passer du modèle du livre à celui de la base documentaire modulaire.
Du document à la base documentaire modulaire Le format de rédaction structurée DITA XML propose de passer du modèle du livre à celui de la base documentaire modulaire.
Formats structurés et non structurés Les informations contenues dans un document technique peuvent être catégorisées selon leur sens.
Formats structurés et non structurés Les informations contenues dans un document technique peuvent être catégorisées selon leur sens.
Une architecture documentaire trop complexe ? DITA XML permet des gains de productivité en réduisant le volume source que le rédacteur technique crée, traduit et maintient, au prix d'une plus grande complexité.
Une architecture documentaire trop complexe ? DITA XML permet des gains de productivité en réduisant le volume source que le rédacteur technique crée, traduit et maintient, au prix d'une plus grande complexité.
Base de données SQL Dans le cas d'un CMS (Content Management System) de type Drupal, Joomla ou WordPress, le référentiel est une base de données SQL.
Collecte de l'information Le rédacteur technique collecte l'information auprès de différentes sources, internes et externes à l'entreprise.
Création du contenu Le rédacteur technique crée le contenu du projet de rédaction technique dans un dialogue constant avec les différents acteurs de la société : services R&D, marketing.
Définition du projet Communiquer des informations techniques sans savoir à qui ni dans quel but est un effort vain.
Format cible Le format cible d'un support de rédaction technique est celui sous lequel l'audience du message y accédera.
Format source Les traitements de texte nous ont déshabitués à distinguer le fond de la forme. Mais confondre les deux entraîne beaucoup d'erreurs et de perte de temps.
Git : du fichier au contenu Sous Git, pensez contenu plutôt que fichiers : c’est plus simple et évite bien des difficultés.
Intégrer la documentation aux processus de développement La documentation fait partie du logiciel.
Les CMS : le workflow en prime, mais une fiabilité à tester S’ils utilisent des formats monolithiques tels que FrameMaker, les rédacteurs techniques peuvent utiliser des CMS tels que SharePoint, Alfresco ou consorts.
Les répertoires réseau partagés - peu adaptés au travail de groupe Les fichiers partagés par une équipe de rédaction technique sont souvent stockés dans un répertoire partagé sur le réseau.
Les systèmes de gestion de versions - rustiques mais fiables Gérer la documentation texte avec un système de gestion de versions (Git, Subversion, SourceSafe) comme le code.
Livraison Le rédacteur technique livre le document à son destinataire de la manière appropriée.
Quel référentiel pour le travail de groupe ? Pour travailler sur un fichier, le rédacteur technique utilise un programme qui lit le fichier sur son disque dur et en charge une copie en mémoire vive.
Référentiel Le contenu est le capital immatériel de la société et doit être protégé comme tel.
Tester les produits pour les documenter Un conte chinois narre comment des aveugles se sont retrouvés confrontés à un éléphant.
Traduction Les contraintes de traduction doivent être prises en compte en amont du processus rédactionnel.
Un référentiel unique ? Idéalement, tout le contenu peut être placé sous un référentiel unique (par ex. Git) pour maximiser réutilisation, cohérence et qualité.
Utiliser les branches des systèmes de gestion de sources Créer des branches dans un gestionnaire de sources pour gérer des projets divergents et les traductions de la documentation.
Validation et contrôle qualité Le contenu doit être validé avant livraison.
Créer des documents différents à partir des mêmes sources via Jinja (méthode objet) Profiler du contenu avec Jinja en définissant des objets (audience, plateforme, version, etc.) pour inclure ou exclure des blocs selon leurs attributs à l’aide d’un script Python profiling.py.
Créer des documents différents à partir des mêmes sources via Jinja (méthode objet) Profiler du contenu avec Jinja en définissant des objets (audience, plateforme, version, etc.) pour inclure ou exclure des blocs selon leurs attributs à l’aide d’un script Python profiling.py.
Créer des documents différents à partir des mêmes sources via Jinja Le script Python profiling.py ci-dessous permet de profiler du contenu en preprocessing à l'aide du puissant moteur de modèle Jinja.
Créer des documents différents à partir des mêmes sources via Jinja Le script Python profiling.py ci-dessous permet de profiler du contenu en preprocessing à l'aide du puissant moteur de modèle Jinja.
Créer des documents différents à partir des mêmes sources ReST (texte conditionnel) Générer des variantes de documents à partir des mêmes sources ReST avec le texte conditionnel de Sphinx.
Créer des documents différents à partir des mêmes sources ReST (texte conditionnel) Générer des variantes de documents à partir des mêmes sources ReST avec le texte conditionnel de Sphinx.
Didacticiels DITA XML et XSL-FO DITA XML est un langage de rédaction structurée qui permet de créer des documents sans se soucier de leur aspect final sur différents supports. XSL-FO est un langage qui permet de réorganiser et filtrer le contenu XML et de lui appliquer une mise en page à l'aide d'une feuille de style.
Didacticiels DITA XML et XSL-FO DITA XML est un langage de rédaction structurée qui permet de créer des documents sans se soucier de leur aspect final sur différents supports. XSL-FO est un langage qui permet de réorganiser et filtrer le contenu XML et de lui appliquer une mise en page à l'aide d'une feuille de style.
Expressions régulières en Python La bibliothèque d'expressions régulières de Python aide à manipuler du texte, notamment si vous n'êtes pas familier avec sed ou awk.
Expressions régulières en Python La bibliothèque d'expressions régulières de Python aide à manipuler du texte, notamment si vous n'êtes pas familier avec sed ou awk.
Insérer automatiquement des données dans un fichier reStructuredText Supposons que vous deviez présenter 3 produits, Dianthus, Geum et Prunus, chacun déclinés dans trois versions 1.0, 1.5 et 2.3.
Insérer automatiquement des données dans un fichier reStructuredText Supposons que vous deviez présenter 3 produits, Dianthus, Geum et Prunus, chacun déclinés dans trois versions 1.0, 1.5 et 2.3.
Insérer automatiquement des données SQL dans un fichier reStructuredText Nous allons créer une base de données de produits avec leurs versions, puis mettre en forme ces informations dans un fichier reStructuredText.
Insérer automatiquement des données SQL dans un fichier reStructuredText Nous allons créer une base de données de produits avec leurs versions, puis mettre en forme ces informations dans un fichier reStructuredText.
Jourdainisation en ligne d'une tirade À l'instar du maître de philosophie du Bourgeois gentilhomme de Molière, un script Python peut facilement intervertir les mots d'une phrase pour dire la même chose de manière plus alambiquée.
Jourdainisation en ligne d'une tirade À l'instar du maître de philosophie du Bourgeois gentilhomme de Molière, un script Python peut facilement intervertir les mots d'une phrase pour dire la même chose de manière plus alambiquée.
Mener un projet de bout en bout Il est assez rare, dans le cadre professionnel, de pouvoir mener un projet de (quasiment) A à Z, de la conception à la communication, en passant par la réalisation.
Mener un projet de bout en bout Il est assez rare, dans le cadre professionnel, de pouvoir mener un projet de (quasiment) A à Z, de la conception à la communication, en passant par la réalisation.
Le Raspberry Pi 3 en tant que plateforme de documentation Avec ses ressources modestes, un Raspberry Pi 3 suffit pour créer, gérer et générer une documentation en PDF, HTML ou EPUB.
Le Raspberry Pi 3 en tant que plateforme de documentation Avec ses ressources modestes, un Raspberry Pi 3 suffit pour créer, gérer et générer une documentation en PDF, HTML ou EPUB.
sed : modifiez votre texte sans ouvrir vos fichiers Les clones d'Unix sont peu utilisés pour gérer la documentation technique.
sed : modifiez votre texte sans ouvrir vos fichiers Les clones d'Unix sont peu utilisés pour gérer la documentation technique.