MS Word nous lance régulièrement des «surprises»: captures d'écran «déplacées», tableaux «flottants», pages blanches lors de l'impression. Cet article explique comment nous recherchions un remplaçant pour MS Word (nous n'avons pas trouvé de spoiler), mais nous avons trouvé une opportunité d'améliorer notre processus de travail avec la documentation à l'échelle mondiale.
Chez Uniscan Research, nous faisons des produits de haute technologie un produit en série. L'entreprise opère dans les secteurs B2G (entreprise à gouvernement) et B2C (entreprise à client).
Notre département développe la conception et la documentation utilisateur des produits en cours de développement, les documents de certification, les supports marketing, la conception et la décoration des bureaux (navigation, panneaux de porte).
Avec les documents du secteur B2C, vous avez la liberté de choisir le format, le nom et le contenu de la documentation. Dans le secteur B2G, environ 70% de la documentation que nous développons doit être préparée conformément aux exigences de l'ESKD et soumise à l'approbation du client au format DOCX.
Nous transmettons à l'utilisateur toute la documentation opérationnelle sous forme imprimée, donc tous les documents sont soumis à une préparation de prépresse. Nos documents ont deux formats cibles: DOCX et PDF.
Pour la mise en œuvre de nos tâches, le département utilise traditionnellement MS Word depuis de nombreuses années.
À chaque nouvelle édition d'un document compilé dans MS Word, dans environ la moitié des cas, des captures d'écran «glissent», des tableaux avec des icônes «flottent» et lorsqu'un document est imprimé, des pages blanches invisibles apparaissent soudainement. Ces opérations de mise en page du document enlèvent à l'auteur du document non seulement le temps, mais aussi le désir de s'engager dans la créativité - le développement de nouveaux documents.
Lors de la prochaine recherche de pages blanches invisibles dans un document DOCX dans notre département, l'idée est venue d'essayer un nouvel outil de développement de documentation. Nous voulions réduire le temps de mise en page et de préparation prépresse du document.
En conséquence, nous n'avons pas pu complètement nous éloigner de l'utilisation de MS Word, mais dans le processus de recherche, nous avons construit un nouveau schéma pour travailler avec la documentation.
Ensuite, je vais essayer de vous dire quels outils pour travailler avec les documents que nous avons envisagés, pourquoi nous avons choisi Confluence en conséquence, quels problèmes nous avons rencontrés et comment nous avons pu les résoudre.
Sélection d'outils
Nous avons lu des articles sur le thème des outils de développement de documentation existants, discuté avec des collègues d'autres sociétés. Les outils suivants nous ont paru les plus adaptés:
- Dita
- DocBook XML
- Confluence
Les deux premiers outils ne convenaient pas pour la même raison: nous avions besoin de compétences en programmation que nous n'avions pas et pour créer un nouveau modèle de document, nous devions faire appel à l'aide d'un programmeur. La transition pour travailler avec eux, selon nos idées, prendrait environ six mois, peut-être plus. En raison des inconvénients ci-dessus, nous avons décidé d'abandonner le test complet de ces outils.
Confluence dès le début a ravi l'éditeur
WYSIWYG- . En moyenne, les rédacteurs techniques ont mis environ une semaine pour maîtriser l'outil, la mise en page des documents «non conforme à GOST» a été plus facile.
Dans les projets B2G, le PDF est important pour nous en tant que format pour la documentation utilisateur. Par conséquent, nous avons immédiatement installé le plug-in approprié pour Confluence - Scroll PDF Exporter. Avec lui, nous avons essayé de créer des modèles personnalisés avec les paramètres nécessaires. Nous étions satisfaits des résultats du test: nous avons établi l'un des documents avec un grand nombre de captures d'écran et d'éléments graphiques dans MS Word pendant environ une semaine; à Confluence, nous avons réussi à disposer le même document en 2 jours et à obtenir une meilleure présentation visuelle.
Nous avons également essayé de configurer le modèle pour Scroll Word Exporter de manière à obtenir un document émis conformément à toutes les règles ESKD. Après deux jours de lecture des guides Confluence et Scroll PDF Exporter et de personnalisation du modèle de spécifications techniques actuel, nous nous sommes rendu compte que cet outil n'était pas adapté au développement de documents exécutés conformément aux exigences d'ESKD.
Ainsi, par exemple, nous n'avons pas pu faire de titres numérotés non gras du deuxième niveau de sorte que le texte ne soit pas un titre, mais un paragraphe. J'ai dû écrire manuellement le numéro de paragraphe et utiliser le style de paragraphe. Il était impossible d'organiser les listes à puces avec un tiret (seulement des cercles, des carrés), les listes numérotées étaient dessinées sans point et les listes de lettres étaient uniquement avec des lettres latines. L'indentation n'a été ajustée que manuellement.
Quelques mois après avoir commencé à maîtriser Confluence, les développeurs de l'outil ont implémenté la fonction d'édition des documents dans leur format d'origine. Cela nous a permis de stocker nos documents "invités" et de créer de nouveaux documents qui ne nécessitent pas une exécution stricte au même endroit. Les fichiers MS Word sont stockés dans Confluence en tant que pièces jointes, lorsqu'ils sont modifiés, ils sont ouverts et enregistrés dans MS Word sur le PC de l'utilisateur, et lors de l'enregistrement, la nouvelle version est automatiquement téléchargée sur Confluence.
Nous avons donc eu l'idée d'utiliser Confluence comme un outil qui résoudrait simultanément trois problèmes:
- Création d'une base de connaissances.
- Développement, stockage et mise à jour de la documentation développée non conforme à GOST.
- Stockage et mise à jour de la documentation développée conformément à GOST.
Confluence potentielle
Nos attentes vis-à-vis de la fonctionnalité Confluence n'ont pas été entièrement satisfaites, mais une fois les tests terminés, une attitude généralement positive envers cet outil s'est formée. Ci-dessous, nous avons formulé ses principaux avantages pour notre département:
- Personnalisez et supportez l'outil par vous-même.
- Facile à apprendre.
- La capacité d'organiser une base de connaissances sur les produits de l'entreprise et de stocker toute la documentation compilée en DOCX et PDF en un seul endroit.
- Prise en charge des documents versionnés.
- Capacité à utiliser une technologie à source unique.
- La possibilité d'un travail conjoint des développeurs et des rédacteurs techniques sur les documents.
- Stockage des documents de travail et des informations en un seul endroit.
- La possibilité de développer des documents à tout moment de n'importe où dans le monde.
Implémentation
Pour implémenter Confluence, nous avons sélectionné deux spécialistes du département rédacteurs techniques qui ont étudié et testé les capacités de l'outil.
Pour une assistance technique continue, le département des administrateurs système nous a affecté un spécialiste. Il a rapidement répondu aux problèmes techniques et a aidé à comprendre les paramètres de base du nouvel outil.
Dans le même temps, nous avons créé un groupe de travail au sein du département rédacteurs techniques, dont la tâche était de planifier la structure de stockage des données. L'ensemble de la structure de notre serveur a été divisé en catégories correspondant aux types de projets de l'entreprise. Les catégories, à leur tour, ont été divisées en espaces par produits de l'entreprise. Nous avons également identifié une catégorie distincte pour la base de connaissances interne.
Lorsque les responsables des tests des systèmes ont étudié le travail dans Confluence assez profondément, l'étape de la formation entre pairs a commencé. Il a fallu environ un mois pour transférer les connaissances à l'ensemble du département.
Problèmes techniques
La mise en œuvre de Confluence dans son ensemble s'est bien déroulée, mais il y a eu des problèmes.
Mise en page et préparation prépresse des documents
«Je le faisais dans MS Word en quelques secondes. Comment faire de même dans Confluence? » - nous nous sommes posé une telle question tous les jours pendant toute la période de test.
Donc, il n'était pas du tout évident d'aligner verticalement le contenu du tableau ou d'attribuer une taille d'icône inférieure à 16 px.
En effet, l'ensemble de base des fonctions de formatage de page dans l'éditeur Confluence WYSIWYG est bien pire que MS Word, mais la fonctionnalité peut être considérablement étendue si vous passez en mode d'édition de code source et travaillez directement avec du code HTML.
Nous avons lu des articles, regardé des vidéos de formation sur la mise en page HTML et partagé les solutions que nous avons trouvées. Nous avons créé une page distincte dans Confluence, où nous avons placé des informations utiles sur l'utilisation de cet outil.
Mise à jour de Confluence et du plugin
Après la première mise à jour du plugin Scroll PDF Exporter principal, 80% des macros se sont envolées et la structure de la page est allée à Confluence. Plus tard, il s'est avéré ce qui s'est passé en raison de la nouvelle fonctionnalité du plugin. Dans tout le département, nous avons restauré la structure des documents pendant plusieurs jours. Après cela, nous avons fait un plan de mise à jour pour l'avenir, auquel nous adhérons toujours:
- Effectuez la mise à jour le vendredi, lorsque la couche principale de travail de la semaine sera terminée afin de pouvoir éliminer les éventuels problèmes le week-end.
- Distribuer à tous les utilisateurs du système pour les informer de l'heure de la mise à jour prévue.
- Avant la mise à niveau, sauvegardez le serveur.
- Mettez à jour la version de Confluence.
- Testez le serveur, assurez-vous que toutes les informations sont en place, les liens vers les ressources externes et internes fonctionnent.
- Si vous devez mettre à jour les plugins, sauvegardez à nouveau le serveur.
- Mettez à jour vos plugins un plugin à la fois.
- Testez le plugin immédiatement après la mise à niveau.
Notifications groupées
Lorsque l'activité turbulente des rédacteurs techniques et des développeurs a finalement commencé à bouillir dans Confluence, l'administrateur a reçu des appels des utilisateurs du service. Ils ont demandé à les sauver d'une attaque de masse par des notifications par courrier électronique concernant les actions d'autres utilisateurs.
Par défaut, l'utilisateur ne devait accéder à une page qu'une seule fois, après quoi il était automatiquement ajouté par le système à la liste des observateurs et recevait des notifications chaque fois que cette page était modifiée.
En plus de cela, Confluence a aimablement envoyé des newsletters hebdomadaires aux utilisateurs répertoriant les pages Confluence les plus populaires. Heureusement, ce problème a déjà été largement couvert sur Internet. La solution consiste à désactiver les notifications correspondantes dans les paramètres système:
Désormais, les utilisateurs ne reçoivent des notifications que si leur nom est mentionné dans les commentaires sur l'article.
Stabilité du serveur
Pour tester Confluence, nous avons déployé un serveur Windows. Dans les étapes initiales, le serveur a souvent «planté». Une partie du problème s'est avérée être une RAM insuffisante sur le serveur (la taille recommandée est de 11 à 12 Go). Les problèmes restants ont disparu lorsque nous avons activé les paramètres système recommandés dans de tels cas.
Maintenant, le serveur fonctionne de manière assez stable - les interruptions se produisent environ 1 fois en 2 mois. En cas de panne, un redémarrage suffit pour le réparer.
Gestion de documents dans Confluence
Aujourd'hui, chez Confluence, les rédacteurs techniques, les programmeurs, les ingénieurs en électronique et le contrôle qualité travaillent ensemble.
Nous avions prévu d'abandonner complètement MS Word, de développer des documents exclusivement dans Confluence et de les convertir en DOCX et PDF. En réalité, il s'est avéré que vous pouvez vous passer du long processus de transfert de toute la documentation existante vers un nouveau format, puis de configuration des modèles dans Scroll PDF / Word Exporter. Selon nos estimations, cela nous prendrait environ six mois pour ce faire. Il s'est avéré beaucoup plus facile de transférer tous les documents développés au format MS Word vers Confluence et de les y conserver.
Nous avons décidé de ne pas nous attendre à un merveilleux formatage de Confluence selon toutes les exigences de l'ESKD et avons simplement divisé conditionnellement tous les documents utilisateur en documents pour le «client étatique» et documents pour le «client non étatique».
Le premier que nous créons au format DOCX, stockons et mettons à jour dans Confluence. Nous développons ce dernier directement dans Confluence, exportons au format PDF si nécessaire.
Grâce aux macros intégrées, nous utilisons la technologie à source unique dans la documentation utilisateur. Désormais, nous n'avons plus à modifier manuellement un paramètre dans plusieurs versions de documents.
L'éditeur WYSIWYG pratique facilite la modification du document fini - les captures d'écran, les icônes et les éléments graphiques restent en place.
La fonction d'édition collaborative vous permet de collaborer sur un document. Vous pouvez partager le document avec un expert technique directement dans Confluence et discuter de ses commentaires en temps réel, plutôt que de diffuser le document à l'infini par courrier.
Pour travailler en dehors du bureau, vous n'avez pas besoin de configurer l'accès à distance. Pour pouvoir travailler à domicile, vous n'avez besoin que d'Internet.
Confluence offre à l'utilisateur l'interface de page Web familière avec la possibilité de configurer des liens croisés et d'ouvrir plusieurs onglets dans le navigateur pour travailler en même temps.
Maintenant, nous stockons tous les documents, éléments graphiques, photos d'appareils, et nous maintenons également une base de connaissances sur les produits de l'entreprise en un seul endroit. Il n'est pas nécessaire de réfléchir à la source des images ou à la dernière version des documents.
Que voulez-vous faire d'autre
Nous mettons actuellement en place le processus d'alignement des pages Confluence à l'aide du plugin Comala Workflow. Cependant, ce plugin ne fonctionne pas avec les pièces jointes MS Word. Nous coordonnons ces documents à l'aide de commentaires de version. Nous envisageons maintenant des options pour définir l'approbation automatique des pièces jointes DOCX. J'aimerais que le processus d'approbation et d'approbation soit utilisé simultanément avec les pages Confluence et les pièces jointes au format DOCX.
Lorsque nous configurerons l'approbation automatique des pièces jointes, nous essaierons de faire une conversion rapide de MS Word en PDF. Et puis - envoyer des documents à notre serveur de produits imprimés, d'où l'imprimerie prend les documents à imprimer.
Instructions de recherche soudaine
Nous n'avons jamais réussi à abandonner MS Word, mais en train de trouver un remplaçant, nous avons soudainement trouvé quelque chose de plus. Confluence a réuni des développeurs de différents départements, constitué la base de connaissances de l'entreprise et est devenu le référentiel de tous les documents de l'entreprise, quel que soit leur format.
Notre entreprise a un principe: dans toute situation incompréhensible, prenez systématiquement des décisions. Nous pensons qu'une solution qui repose sur un modèle est meilleure qu'une solution basée sur une opinion ou une intuition d'experts.
Dans le cas de Confluence, le modèle d'Eric Rhys de The Lean Startup s'est avéré utile. Dans le développement de produits, il permet de pivoter, de changer la direction du développement de produits. Et dans la tâche de trouver un remplaçant pour MS Word, essayez un nouvel outil plus largement et trouvez les avantages associés.
Nous souhaitons à nos collègues rédacteurs techniques des modèles utiles!