Dokiel Guide

Une chaîne éditoriale dédiée aux manuels techniques

Dokiel optimise la conception de manuels utilisateurs, publiés au format web et papier et de sites documentaires de référence.

Rédiger et structurer la documentation

Les items fondamentaux

Dokiel structure le Guide en Sections arborescentes.

Le contenu de ces sections s'appuie sur 3 types d'items fondamentaux, constitutifs d'une documentation :

  • Le Concept permet de décrire les notions utiles à connaître pour utiliser l'outil ou le logiciel : notions liées au métier, définitions des termes propres à l'outil. Il permet de constituer un glossaire riche.

  • La Procédure permet de recenser les fonctionnalités de l'outil et d'expliciter les actions à réaliser, sous forme de vidéos et également d'un enchaînement d'étapes illustrées par des images et s'affichant pas à pas.

  • L’Écran permet de documenter un écran applicatif par une image enrichie d'explications. Sur le support web, l'écran devient interactif.

Des blocs d'intention dédiés

Les blocs d'intention sont adaptés à la documentation technique et permettent de diffuser des Alertes, des TIP'S, des bonnes pratiques...

Un balisage adapté

Pour la documentation d'un logiciel, le balisage du texte est conçu pour simplifier l'écriture, éviter des copies d'écrans, aider à la lecture.

La mise à jour des copies d’écran accroît le temps de mise à jour de la documentation, il est possible de les remplacer par un texte enrichi avec des balises inline permettant de mettre en valeur des objets graphiques de l'interface utilisateur du logiciel :

  • radio-bouton ;

  • chemin de menu ;

  • bouton textuel ;

  • case à cocher ;

  • ...

L'intégration de ressources : vidéos, images...

Des photographies, copies d'écrans, vidéos, vidéos d'écrans, enchaînements d'images illustrent le fonctionnement de l'outil.

Recombiner pour créer de nouveaux guides

Des fragments de contenus peuvent être réutilisés entre deux documentations (un guide de démarrage, une documentation avancée...), par référence (sans recopie) :

  • les items fondamentaux ;

  • un ensemble d'étapes de procédures ;

  • les ressources (images...) ;

  • la Partie et le Fragment.

En concevant votre contenu sous forme de fragments, vous pouvez les réutiliser, les recombiner et ainsi optimiser votre temps de mise à jour (l'information est mise à jour une seule fois, à un seul endroit) et assurez une meilleure cohérence de l'ensemble de vos documentations (l'information est identique partout).

Utiliser les filtres, les variables, les calques de dérivation pour adapter son contenu

Des techniques avancées permettent de réaliser une variation du contenu sans pour autant le dupliquer. Le contenu a souvent besoin d'être adapté, soit pour un support donné (par exemple l'impression), pour un public (débutant, avancé), pour un usage (interne, client...)... Par exemple, Dokiel permet :

  • de définir une variable (le nom d'un outil) - ou plusieurs par paramétrage de la chaîne éditoriale

  • de filtrer un contenu (version courte - standard) en l'excluant d'un document qui exploite explicitement la totalité du contenu, à l'exception du contenu exclu

  • d'organiser un atelier maître et des calques de dérivation qui permettent de faire varier une partie du contenu, de le spécialiser pour un usage donné.

Publier le guide dans 2 formats

Le guide utilisateur se publie sous deux formes :

  • web pour une diffusion en ligne sur Intranet, GED, Internet via FTP ou sur CD/DVDRom, clé usb... ;

  • papier (PDF) pour une diffusion sous forme de téléchargement ou une édition.

Réaliser une documentation de référence

Autant le Guide peut être vu comme un Manuel à lire et étudier de bout en bout, car il intègre un scénario didactique progressif, autant le Site de référence est destiné à présenter plusieurs points d'entrée permettant d'apporter des réponses à une question précise que se pose l'utilisateur.

Pour cela, 4 points d'entrée lui sont proposés :

  • le moteur de recherche

  • l'index des Procédures, qui liste et classe par ordre alphabétique les procédures d'utilisation de l'outil

  • le Glossaire, qui recense l'ensemble des Concepts

  • une arborescence de Thèmes.

La Documentation de référence se publie au format Web et est structurée sous forme arborescente, de Thèmes et sous-thèmes et directement de Rubriques qui référencent les Items communs de Dokiel (Procédure, Écran, Concept) et les Sections du Guide.

Collaborer : organiser le travail d'une équipe

  1. Organiser son propre travail : post-it, marque-pages

  2. Échanger entre collaborateurs via des tâches

  3. Faire relire et valider, via le web

Droits d'accès

Des rôles simples, sont proposés en standard dans l'application :

  • Aucun

  • Lecteur

  • Rédacteur

  • Gestionnaire (mettant à jour l'application).

  • Contributeur : pour autoriser à un Lecteur la fonction de relecture par le web.

La liste des utilisateurs est définie dans l'application Scenari. L'authentification peut être réalisé avec Scenari ou en connectant Scenari à votre annuaire LDAP.

Les droits d'accès devant se caler à l'organisation, ils sont fortement configurables à l'aide de l'outil SCENARIbuilder. Leur gestion nécessite un travail fonctionnel permettant d’identifier votre organisation (les équipes, les rôles, le droits et interdictions), vos processus de fonctionnement et en déduire les autorisations d'accès nécessaires.

Localiser

Dokiel permet de suivre la traduction de vos contenus et leur adaptation au contexte du pays, en utilisant la technique de calque de dérivation.

Déploiement

Dokiel se déploie en deux modes principaux selon vos contextes techniques et d'usage.

Dokiel en mode desktop

Dokiel s'installe en mode local, avec un stockage sur un disque dur local des contenus Xml.

En savoir plus ...

Quelques exemples de contextes :

  • évaluation de chaînes éditoriales et tests de prototypes ;

  • usages sans écriture collaborative...

Dokiel en client-serveur

Afin de faciliter le travail à plusieurs rédacteurs, un déploiement en mode client-serveur de la chaîne éditoriale est disponible.

En savoir plus ...

SCENARIserver est un serveur de contenu, conçu comme une Webapp à installer dans un serveur de servlets Java tel que Tomcat.

En mode client-serveur, le serveur effectue les tâches :

  • de stockage des contenus ;

  • de génération des documents.

Le client Scenari qui fournit l'interface d'édition se déploie sous forme de client lourd, sur les postes clients Mac, Linux, Windows.

De la documentation à la formation...

En utilisant les sources de Dokiel librairie dans l'outil SCENARIbuilder, Dokiel se configure pour ajouter des composantes de formation :