Rédiger des documentations à l'aide de Dokiel

Transcription

1 Rédiger des documentations à l'aide de Dokiel Direction des Usages du Numérique

2 Version : 2.0 Date : Février 2015 Editeur : Auteur(s) : Copyright : Licence : Université de Strasbourg Stéphanie Torrent, Amaury Seiler, Christophe Scherrer Direction des Usages du Numérique Licence Creative Commons : Paternité - Partage des Conditions Initiales à l'identique 2

3 TABLE DES MATIÈRES Présentation générale... 4 Chapitre 1 - Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel L'interface de DOKIEL pour la construction de son guide 5 2. L'interface d'une documentation web construite avec DOKIEL 11 Chapitre 2 - Installer le logiciel d'édition des documentations DOKIEL à distance sur un serveur dédié - ScenariServer 17 Chapitre 3 - Création d'une documentation utilisateur Construire et publier sa documentation Construire l'ossature de sa documentation, organiser son espace de travail Rédiger les contenus Publier le guide, générer les contenus Générer la création des supports Diffuser sa documentation 39 Chapitre 4 - Nouveautés Dokiel Chapitre 5 - Nouveautés Dokiel Pour aller plus loin Glossaire

4 Rédiger des documentations à l'aide de Dokiel Présentation générale PRÉSENTATION GÉNÉRALE Dokiel, une chaîne éditoriale Dokiel (en référence à Documentation et à logiciel) est une chaîne éditoriale qui permet de rédiger des guides ou manuels utilisateur. Dokiel Guide repose sur l'utilisation de ScenariChain. ScenariChain est un logiciel de gestion de chaînes éditoriales. Parmi les chaînes éditoriales, on trouve par exemple aussi Opale [ umentationlogicielle.u-strasbg.fr/dun/ipm/opale/co/_guide.html - Chaîne éditoriale OpaleSup pour l'uds], chaîne éditoriale adaptée à la production de ressources pédagogiques ou modules de formation de types académiques. Elle est également utilisée à l'université. Qu'est-ce qu'une chaîne éditoriale? Une chaîne éditoriale est un procédé technologique qui permet, d'une part, de rédiger de façon assistée un contenu (aide à la structuration et à la mise en forme) à partir d'un environnement de travail unique, d'autre part de décliner de façon automatique la publication de sa documentation sur différents supports, en l'occurrence un support web et/ou un support PDF pour impression papier. Dokiel est une chaîne éditoriale «orientée métier» : elle propose des items de rédaction adaptés aux besoins spécifiques de la documentation logicielle. On trouvera ainsi par exemple des mises en forme spécifiques pour : des écrans commentés (zone par zone), ou des descriptions de procédures à suivre. On pourra créer simplement : des animations par enchaînement d'images (sans utiliser de logiciel de création de tutoriel animé) ou un glossaire des concepts liés à une application. Pour en savoir plus, consulter Scenari Platform [ le site officiel. Contenus de ce guide Ce document présente : l' Interface de Dokiel avec la découverte de l'interface d'édition (du point de vue du rédacteur) et d'un exemple de documentation (aperçu du point de vue du lecteur) ; les modalités d'accès à la chaîne éditoriale via ScenariServer ; les modalités de création et de diffusion de sa Documentation. Cette documentation a elle-même été rédigée à l'aide de Dokiel. 4 Février 2015 Version : 2.0 Direction des Usages du Numérique

5 Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel Rédiger des documentations à l'aide de Dokiel CHAPITRE 1 COMPRENDRE LA STRUCTURE D'UN DOCUMENT RÉALISÉ AVEC LA CHAÎNE ÉDITORIALE DOKIEL Avant de commencer le travail de rédaction de son guide utilisateur via l'interface d'édition de Dokiel, il est conseillé de réfléchir aux contenus possibles afin d'en définir l'ossature générale. Une bonne connaissance des possibilités du logiciel aide ensuite à vraiment structurer les différents éléments de contenus et à réfléchir à la granularité du découpage. Certains items pourront ainsi être utilisables dans plusieurs guides par exemple. 1. L'interface de DOKIEL pour la construction de son guide Présentation générale L'espace de travail est découpé en deux parties essentielles. l'espace de navigation et d'arborescence des dossiers et fichiers (partie de gauche sur l'image ci-après), la zone de rédaction des contenus (partie droite de l'écran sur l'image ci-après). Février 2015 Version : 2.0 Direction des Usages du Numérique 5

6 Rédiger des documentations à l'aide de Dokiel Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel 1 1. L'espace de navigation et d'arborescence des dossiers et fichiers (partie de gauche sur l'image ci-après). Il est possible de créer un ou des espaces de travail et accéder à l'éditeur ou grille de saisie des contenus. Dans cet exemple plusieurs espaces (dossiers) ont été créés dont un reprenant la logique de classement du catalogue des services numériques La zone de rédaction des contenus. A ce stade le travail d'édition n'a pas commencé. L'écran est vierge. 6 Février 2015 Version : 2.0 Direction des Usages du Numérique

7 Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel Rédiger des documentations à l'aide de Dokiel Un exemple d'utilisation avancée de Dokiel. Dans cet exemple plus complet, l'espace de navigation présente un ensemble d'ateliers, espaces et items, qui organisent et structurent la documentation. L'espace de travail est ouvert sur la grille de saisie de ce que l'on appelle une section. Ici 1_1Interface_Edition_contenus.scen 1 Retour à l'accueil Pour retrouver la liste des ateliers de l'entrepôt distant auxquels on a accès. Pour se déconnecter du serveur. Février 2015 Version : 2.0 Direction des Usages du Numérique 7

8 Rédiger des documentations à l'aide de Dokiel Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel 2 L'espace de navigation L'espace de navigation comprend les différents ateliers, espaces, et items constitutifs des différentes documentations. L'explorateur de fichiers de l'atelier Ici il s'agit de l'atelier Documentation logicielle dans lequel on trouve plusieurs espaces de stockage ou classement. Les espaces et items constitutifs des documentations Qu'est-ce qu'un espace? Il s'agit d'un dossier de classement des ressources constitutives de la documentation. Comment se présente un espace? Les espaces sont représentés par des dossiers verts : ouverts :, ou fermés :. (Cliquer sur la flèche pour fermer ou ouvrir un espace). On trouve ensuite les éléments de contenus, les items : des guides utilisateur 8 Février 2015 Version : 2.0 Direction des Usages du Numérique

9 Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel Rédiger des documentations à l'aide de Dokiel des guideweb et guidepapier (supports de diffusion) des sections des parties etc. Il sera parfois bienvenu de regrouper certains types d'items dans un même espace : les ressources images par exemple. 3 L'espace de travail C'est l'espace central à partir duquel : on rédige, guidé par la grille de saisie et de structuration des contenus ; on compose la documentation, en intégrant les différents items ; en toute fin, on produit la documentation, ou, dans le vocabulaire Scenari, on «génère» le document. Février 2015 Version : 2.0 Direction des Usages du Numérique 9

10 Rédiger des documentations à l'aide de Dokiel Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel 4 Outil de recherche Pour effectuer des recherches au sein de l'atelier ou dans un espace. 10 Février 2015 Version : 2.0 Direction des Usages du Numérique

11 Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel Rédiger des documentations à l'aide de Dokiel 5 Autres options d'affichage Affichage du réseau et du plan d'un item (pour voir les liens entre items, la structuration item parent item descendant). Affichage de l'historique des versions. Gestion de Marque-pages personnel 2. L'interface d'une documentation web construite avec DOKIEL Il s'agit du résultat de la génération du guideweb du guide utilisateur de Dokiel. Présentation générale La documentation s'ouvre sur une page découpée de la façon suivante. Février 2015 Version : 2.0 Direction des Usages du Numérique 11

12 Rédiger des documentations à l'aide de Dokiel Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel 1 Toute documentation présente un titre principal. Le logo Unistra est automatiquement inséré à toute documentation, sans action de la part du rédacteur. 2 I est possible d'ajouter, si besoin, le logo de l'application décrite. 12 Février 2015 Version : 2.0 Direction des Usages du Numérique

13 Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel Rédiger des documentations à l'aide de Dokiel 3 Menu qui présente l'arborescence des sections. La section sélectionnée Installer la chaîne éditoriale apparaît en gras. Elle comporte elle-même des sous-sections : Construire et publier sa documentation, Publier le guide, générer les contenus. 4 Les contenus eux-mêmes. 5 Un retour toujours possible au document principal : bouton Guide. Un affichage du mode Plan interactif de la documentation. Février 2015 Version : 2.0 Direction des Usages du Numérique 13

14 Rédiger des documentations à l'aide de Dokiel Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel On trouvera ici aussi le cas échéant le Glossaire des termes utilisés dans la documentation. 6 En bas de page, on trouve des informations de type : auteur, éditeur, version du document. Voir en particulier la rubrique «A propos». L'organisation d'un guide Un travail préalable de découverte de la structure d'une documentation aide à la prise en main de Dokiel. Elle permet d'établir la correspondance entre les différentes parties d'un guide et les champs de saisie et items constitutifs de Dokiel. Découpage d'une documentation Une documentation est découpée de la façon suivante : Une «première page» (non obligatoire). Cette première rubrique dite de description permet de donner des indications concernant le contenu du guide web et le public cible. Si elle n'est pas renseignée, la documentation commence directement par l'introduction (ci-dessous renommée «Présentation générale»). Une introduction (non obligatoire). Des sections c'est à dire différents chapitres thématiques. Une conclusion (non obligatoire). Une section peut être déclinée en sous sections intégrant elles-mêmes un niveau inférieur encore de sections, etc.. Une section peut également comporter des parties. A partir de quatre éléments de ce type, parties et sous-parties confondues, un sommaire s'affiche alors automatiquement. 14 Février 2015 Version : 2.0 Direction des Usages du Numérique

15 Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel Rédiger des documentations à l'aide de Dokiel 1 La section «Création d'une documentation utilisateur» contient : la section «Construire et publier sa documentation» qui contient : la section «Construire l'ossature de sa documentation, organiser son espace de travail» et la section «Rédiger les contenus». Cette dernière est en cours de consultation. Noter : - la mise en valeur de l'hyperlien dans le menu de navigation et - le fil d'ariane sous le bandeau gris. Février 2015 Version : 2.0 Direction des Usages du Numérique 15

16 Rédiger des documentations à l'aide de Dokiel Comprendre la structure d'un document réalisé avec la chaîne éditoriale Dokiel 2 Dans cet exemple, 1. la section «Rédiger les contenus» comporte elle-même deux parties : Items constitutifs et Items proposés aux utilisateurs de Dokiel Guide UdS. 2. Chaque partie contient elle-même des sous-parties. 16 Février 2015 Version : 2.0 Direction des Usages du Numérique

17 Installer le logiciel d'édition des documentations Rédiger des documentations à l'aide de Dokiel INSTALLER LE LOGICIEL D'ÉDITION DES DOCUMENTATIONS CHAPITRE 2 Pour rédiger sa documentation logicielle, il est possible de travailler : en local sur son ordinateur, ou à distance sur un espace dédié, appelé ScenariServer. Cette deuxième possibilité est celle que nous conseillons : elle offre des avantages tels que la gestion des mises à jour de la chaîne et le travail collaboratif. On utilise 1) le logiciel SCENARIclient et 2) le modèle documentaire Dokiel Guide, décliné pour l'université de Strasbourg. SCENARIclient permet : de se connecter à ScenariServer sur lequel sont installés les modèles documentaires Opale pour des contenus pédagogiques ou Dokiel Guide pour des documentations logicielles, puis de créer des contenus, et de publier ces contenus conformément aux modèles. Pour Dokiel Guide, un habillage spécifique a été créé, respectant la charte graphique des documents papier et web de l'université de Strasbourg. Tout comme les ressources pédagogiques produites avec Opale [ - Chaîne éditoriale OpaleSup pour l'uds], les documentations produites avec Dokiel seront donc aux couleurs de l'unistra, répondant à des critères de présentation définis en interne à l'établissement. Le modèle a évolué depuis la date de création de la documentation. Les principes d'utilisation restent cependant identiques. 1. DOKIEL à distance sur un serveur dédié - ScenariServer Présentation pas à pas de la procédure d'installation de ScenariClient et d'accès à ScenariServer pour l'utilisation de Dokiel. Il est nécessaire de disposer au préalable des droits d'accès à ScenariServer. Faire un ticket au support libellé [Documentation - Compte utilisateur Dokiel], en indiquant le nom de l'outil pour lequel ou le contexte dans lequel la documentation doit être rédigée. Le ticket est transmis au département IPM de la DUN. Installer SCENARIclient Cette procédure, sauf évolution de la version de SCENARIclient, ne demande à être effectuée qu'une seule fois. La procédure d'installation en images Février 2015 Version : 2.0 Direction des Usages du Numérique 17

18 Rédiger des documentations à l'aide de Dokiel Installer le logiciel d'édition des documentations 18 Février 2015 Version : 2.0 Direction des Usages du Numérique

19 Installer le logiciel d'édition des documentations Rédiger des documentations à l'aide de Dokiel Février 2015 Version : 2.0 Direction des Usages du Numérique 19

20 Rédiger des documentations à l'aide de Dokiel Installer le logiciel d'édition des documentations 20 Février 2015 Version : 2.0 Direction des Usages du Numérique

21 Installer le logiciel d'édition des documentations Rédiger des documentations à l'aide de Dokiel Télécharger l'application adaptée à son système d'exploitation (OS) Pour Windows [ Linux 32 bits [ Linux 64 bits [ Pour Mac [ Exemple pour Windows : Cliquer sur le fichier '. exe' puis l'enregistrer. Lancer le programme d'installation. Février 2015 Version : 2.0 Direction des Usages du Numérique 21

22 Rédiger des documentations à l'aide de Dokiel Installer le logiciel d'édition des documentations Une fois le fichier enregistré sur son ordinateur, double-cliquer sur le fichier '.exe' : Exécuter. L'installateur de SCENARIclient s'ouvre. Suivre les étapes proposées, accepter les termes de la licence, choisir le dossier d'installation et cliquer sur Installer. Cliquer sur Fermer pour valider l'installation et lancer SCENARIclient. Activer sa connexion à ScenariServer Une fois SCENARIclient installé, et à réception du compte utilisateur Scenari, lancer le logiciel et se connecter au serveur en suivant la procédure ci-dessous. Paramètres de connexion au serveur SCENARI Choisir " " dans le menu de droite. Menu de droite... Une fenêtre s'ouvre Février 2015 Version : 2.0 Direction des Usages du Numérique

23 Installer le logiciel d'édition des documentations Rédiger des documentations à l'aide de Dokiel Entrer les informations suivantes : URL : Titre : ScenariServer UNISTRA Compte : Votre identifiant E.N.T Mot de passe : si vous aviez déjà un compte sur le serveur Scenari, votre mot de passe n'a pas changé ; sinon, il vous a été communiqué dans le mail de confirmation de création de compte. Cliquer le bouton Créer. Mot de passe oublié Si vous avez oublié votre mot de passe, écrivez à support@unistra.fr [mailto:support@unistra.fr] avec pour objet du message : Serveur Scenari : mot de passe oublié Entrer dans l'atelier Documentation Logicielle Cliquer sur ScenariServer UNISTRA : Puis cliquer sur le bouton Ouvrir en face de Documentation Logicielle : Personnalisation de son mot de passe Cliquer sur le bouton Propriétés en face de ScenariServer UNISTRA. Dans l'onglet Mon Profil, cocher mot de passe, saisir et confirmer son mot de passe personnalisé. Cliquer enfin le bouton Enregistrer. Février 2015 Version : 2.0 Direction des Usages du Numérique 23

24 Rédiger des documentations à l'aide de Dokiel Création d'une documentation utilisateur CHAPITRE 3 CRÉATION D'UNE DOCUMENTATION UTILISATEUR Préalable Lorsqu'on rédige à l'aide d'une chaîne éditoriale, le document est éclaté en plusieurs fichiers contrairement à la rédaction à partir d'un logiciel de bureautique où les contenus sont tous saisis les uns à la suite des autres et donc regroupés au sein d'un seul et même document. Cet «éclatement» va permettre une gestion modulaire des contenus. Le rédacteur peut ainsi définir la création d'objets qui pourront être réutilisés dans un contexte pour un autre document. De prime abord, la gestion des contenus paraît complexe. En réalité elle aide dans la structuration ou l'organisation de ses contenus. Il va nous falloir simplement être rigoureux. La logique de classement est similaire à celle du classement dans des répertoires, dossiers, sous-dossiers, fichiers de son ordinateur personnel. Elle est donc familière. Au commencement, elle passe par la création d' espaces Construire et publier sa documentation 1.1. Construire l'ossature de sa documentation, organiser son espace de travail Il s'agit ici de construire le squelette de sa documentation. Créer un espace Un espace est un dossier. Il est stocké dans un atelier lui-même déposé dans un entrepôt distant thématique. Pour créer un espace, choisir le dossier de destination dans l'arborescence de l'explorateur de fichiers, faire un clic droit. Choisir Créer un espace. Une fenêtre s'ouvre. Saisir le nom de cet espace (éviter les accents) et cliquer sur OK. Créer un item racine guideweb ou guidepapier 24 Février 2015 Version : 2.0 Direction des Usages du Numérique

25 Création d'une documentation utilisateur Rédiger des documentations à l'aide de Dokiel La seconde étape consiste en la création du premier item du guide, l'item racine. L'item racine est l'item de plus haut niveau. Il est celui qui définit le format de publication du Guide utilisateur. Il existe deux modes principaux de publication automatisée du guide : le guide web et le guide papier généré au format PDF. Cliquer sur l'espace de la documentation. Faire un clic droit et choisir Ajouter un item... Choisir alors le type d'item : Guide web dans un premier temps. Choix du support - Item racine Ne pas renommer ces deux items. Au niveau du champ «Nom de l'item», noter le nom de l'extension :.pub pour publication (à ne pas effacer). Cliquer sur le bouton Créer. Recommencer cette procédure pour le Guide papier. Le Guide papier sera ultérieurement, manuellement, inséré au Guide web. Créer un Guide utilisateur Il s'agit de l'item qui permet de composer la documentation, de rassembler les éléments constitutifs. Un Guide est composé de «sections», ce qui correspond à des parties ou chapitres. Toutes les sections créées seront donc rattachées à ce Guide avant publication du support final, web ou papier. Faire un clic droit sur l'espace de la documentation concernée et choisir Ajouter un item... Choisir : Février 2015 Version : 2.0 Direction des Usages du Numérique 25

26 Rédiger des documentations à l'aide de Dokiel Création d'une documentation utilisateur L'item créé est un «guide.scen». Pour plus de clarté, et surtout pour le situer aisément dans l'arborescence, il peut être renommé : soit en «guide utilisateur.scen», soit en «guide_nom_du_service» etc. Résultat : Ci-contre les items du guide utilisateur à renseigner. Titre (exemple : Guide utilisateur Dokiel) Introduction On trouve ensuite : et les sections constitutives du document (Chapitres) la conclusion. Pour accéder à l'espace de rédaction du texte de l'introduction et de la conclusion, double cliquer sur. L'espace de rédaction est alors déployé. La signale que les éléments manquants sont obligatoires. Renseigner un titre ; Rattacher, a minima, une section. On peut dès à présent définir le squelette du document en rattachant les sections ou parties constitutives de la documentation. Les contenus pourront être rédigés ultérieurement. Enregistrer Créer les sections du Guide utilisateur Créer une première section Pour ajouter une section, double cliquer sur pour ouvrir cette nouvelle fenêtre. Cliquer sur Créer un nouvel item... en bas de page à gauche). (bouton L'item à créer est alors du bon type. 26 Février 2015 Version : 2.0 Direction des Usages du Numérique

27 Création d'une documentation utilisateur Rédiger des documentations à l'aide de Dokiel Définir le nom de section et cliquer sur Créer. La section apparaît dans l'arborescence. La grille de saisie des contenus pour cette section s'ouvre. A ce stade, une section présente a minima un titre. Les éléments constitutifs d'une section sont les suivants : un titre principal ; un titre court : le titre utilisé dans l'arborescence de navigation (côté lecteur) ; un corps ou introduction ; une (ou des) section (qui devient de fait une sous-section) qui peut contenir une ou des parties ; et une rubrique Voir aussi (pour renvoi possible vers d'autres sections ou vers un document PDF). Enregistrer la modification à l'aide de Cliquer sur Sélectionner (bas de page). La section est ajoutée au guide utilisateur. Oups! Le titre du guide n'a toujours pas été rédigé! Février 2015 Version : 2.0 Direction des Usages du Numérique 27

28 Rédiger des documentations à l'aide de Dokiel Création d'une documentation utilisateur C'est fait! Je n'oublie pas d'enregistrer... Ajouter une seconde section Cliquer sur pour afficher et cliquer sur Section. Double cliquer alors sur etc. A ce niveau de création (ossature du guide utilisateur) une section est nécessairement «externalisée». Créer les espaces de stockage des images Plusieurs niveaux de classement des ressources pour le guide peuvent bien sûr être imaginés : regroupement de tous les fichiers pdf, de tous les fichiers vidéo, de toutes les définitions, etc. Ici on crée un espace de stockage de toutes les images utilisées pour le guide Rédiger les contenus Différents items vont permettre de guider, via l'éditeur WYSIWYM*[p.45], la structuration et la rédaction des contenus. Dokiel présente en effet plusieurs catégories d'items chacun porteur d'une structure prédéfinie qui va aider dans la présentation des contenus. Items constitutifs 28 Février 2015 Version : 2.0 Direction des Usages du Numérique

29 Création d'une documentation utilisateur Rédiger des documentations à l'aide de Dokiel Les balises de saisie Bloc Information Il va permettre : 1. la saisie de : texte simple ; texte illustré ; 2. l'intégration d'une illustration de type... Un exemple d'enchaînement de copies écran [ u-strasbg.fr/dun/ipm/moodle/filtre_utilisateurs/co/procedure_userlist.html] Simulation de la procédure». : Bouton «3. l'insertion d'une rubrique «Voir aussi» : renvoi vers une référence, c'est à dire une autre partie du document (un des items de l'arborescence des fichiers) ou renvoi vers un fichier PDF. Voir aussi «Voir aussi»! Présentation de la rubrique «Voir aussi» (cf. Présentation de la rubrique «Voir aussi») Procédure Il permet la présentation d'une procédure à suivre. Elle est découpée en étapes. Ce bloc comporte : un titre, une introduction, un aperçu potentiel en images sous forme de un ensemble d'étapes, des commentaires généraux, et la possibilité de présenter une procédure alternative. Elle peut être externalisée. Grille de saisie de la procédure Concept Il permet de présenter et mettre en valeur une notion importante présentée. Il présente un champ Synonyme et un champ Définition. a priori liée à l'application Février 2015 Version : 2.0 Direction des Usages du Numérique 29

30 Rédiger des documentations à l'aide de Dokiel Création d'une documentation utilisateur Il peut être externalisé. Grille de saisie du concept. Écran Il repose sur l'utilisation d'une copie d'écran de l'application et sur la description de différentes zones positionnées sur cette copie écran. Grille de saisie d'un écran. Les éléments considérés comme obligatoires pour chaque bloc cité sont marqués d'une. Comment insérer un bloc? Cliquer sur l'astérisque. Chaque permet d'ajouter la bonne rubrique parmi celles proposées dans la liste contextualisée. La mise en forme du texte Les possibilités de mise en forme du texte sont multiples : la création de paragraphes à l'aide des ou des ; les listes que l'on trouve dans le menu supérieur ; les tableaux simples. Certains paragraphes seront mis en forme de telle manière qu'ils exprimeront l'intention du rédacteur : proposer une astuce, faire remarquer un point important, donner un conseil, alerter etc. L'accès aux options de mise en forme du texte s'effectue : depuis le menu supérieur ou à l'aide d'un clic droit pour afficher Février 2015 Version : 2.0 Direction des Usages du Numérique

31 Création d'une documentation utilisateur Rédiger des documentations à l'aide de Dokiel On trouve : Deux notions particulières : Important : mise en valeur du texte en gras ; Équivalent (pour signaler qu'il s'agit d'une expression) : mise en valeur du texte en italique. Huit types de «Blocs» : le bloc Information (vu précédemment) et les blocs... Utiliser pour ajouter l'un ou l'autre type de bloc. Attention Conseil Truc et astuce Exemple Remarque Réglementaire Complément L'icône associé à chaque bloc, également mis en valeur par un encadré de couleur, met en évidence l' intention particulière du rédacteur : donner un exemple, fournir une information complémentaire etc. Du point de vue du lecteur, les blocs se présentent de la façon suivante : Attention Conseil Truc et astuce Exemple Remarque Réglementaire Complément Le texte peut être agrémenté d'images, de boutons icônes ou d'éléments visuels que l'on retrouve souvent dans des environnements informatiques : Février 2015 Version : 2.0 Direction des Usages du Numérique 31

32 Rédiger des documentations à l'aide de Dokiel Création d'une documentation utilisateur On obtient un affichage de cet ordre là : Onglet textuel Bouton textuel Bouton radio textuel Case à cocher textuelle Touche clavier Chemin d'un menu Label Chemin de fichiers, nom de fichier Ligne de commande Bouton icône - Pour ajouter une image de type icône dans le texte (.icon.png ou.icon.gif) Copie d'écran - Pour ajouter une copie d'écran directement dans le texte (.scr.png ou.scr.gif). Pour supprimer une mise en forme : clic droit et... Les items de référence Il est possible de créer des liens externes ou vers d'autres éléments du guide. On trouve : Lien externe pour créer un lien vers une URL en [ ou [mailto :...@unistra.fr] dans le corps du texte. Exemple : Consulter le site de l'uds. Définition pour créer un lien vers une définition (item en «*.ref»). Exemple : Définition de Dokiel Guide*[p.45] Valeur(s) de référence pour créer un lien vers un item en «*.ref». Présentation de la ou des valeurs de référence utilisée(s) Entrée bibliographique pour créer un lien vers un fichier «*.ref». Entrée bibliographique Référence à une ressource web pour créer un lien vers un fichier «*.url». Référence à une ressource web [ - Unistra] Pour modifier un lien, une référence : sélectionner ou se se positionner sur l'élément et faire un 32 Février 2015 Version : 2.0 Direction des Usages du Numérique

33 Création d'une documentation utilisateur Rédiger des documentations à l'aide de Dokiel clic droit... Items proposés aux utilisateurs de Dokiel Guide UdS Quelques items sont mutualisables et ont donc été pré-rédigés pour être mis à disposition de tout utilisateur de Dokiel via ScenariServer. L'intention de départ est de faciliter la rédaction de certains objets communs à tous, de faire gagner du temps à chacun et d'homogénéiser la présentation des documentations de l'université. Nous suivons le principe ici de l'optimisation de la production documentaire que permet déjà la chaîne éditoriale : garantir une charte éditoriale et graphique, automatiser un maximum de choses. Il s'agit de : l'aide (coordonnées du support), la personnalisation de l'ent, le glossaire, les informations rédacteur(s). Ils peuvent : soit être directement exploités en l'état, soit être copiés pour adaptation. Présentation des items Aide/Assistance Cet item d'aide est commun à tous dans le sens où il fournit les coordonnées du support aux lecteurs de la documentation qui sera produite : mail, téléphone, formulaire en ligne. Dans Items Communs, Exemples_structuration_documentation, documentation_de_type_manuel, voir la section 4_disponibilité si vous avez besoin de créer une dernière partie d'alerte concernant la disponibilité de l'application. Personnalisation de l'ent La plupart des applications de l'université sont mises à disposition via l'ent. Dans certains cas, il pourra s'agir d'applications accessibles via la personnalisation. Un item de présentation de la personnalisation est donc proposé. Voir l'aide des Signets (dossier Canaux ENT dans DUN IPM) pour un exemple d'intégration de ce contenu dans la documentation. Glossaire Certains termes sont récurrents et se retrouvent d'une documentation à l'autre. Février 2015 Version : 2.0 Direction des Usages du Numérique 33

34 Rédiger des documentations à l'aide de Dokiel Création d'une documentation utilisateur Exemple : Canal ENT, Fil d'ariane. Des définitions par défaut sont ainsi proposées, mais peuvent bien sûr être complétées ou adaptées. Créer alors un glossaire spécifique à sa documentation. Informations rédacteurs Chaque documentation présente un «A propos» qui consiste en la présentation des éléments suivantes : version du document, date, rédacteur du document (dont structure de rattachement), éditeur, licence. Copie des items Si l'item ou l'espace se trouve dans le même atelier que celui dans lequel on travaille : effectuer un clic droit puis Copier et Coller. Voir aussi... Aperçu de sa documentation en cours de rédaction Voir aussi... Aperçu de sa documentation en cours de rédaction 2. Publier le guide, générer les contenus La publication est la phase pendant laquelle la chaîne éditoriale va transformer les données saisies pour aboutir au support de lecture finalisé. Vérifier ses contenus Avant toute autre opération, il est important de vérifier que tous les contenus sont enregistrés et qu'aucune erreur ne subsiste. Supprimer la présence de la moindre erreur, enregistrer tous les contenus. Croix rouge Un contenu présentant une croix rouge contient une erreur. Ces croix rouges apparaissent : 34 Février 2015 Version : 2.0 Direction des Usages du Numérique

35 Création d'une documentation utilisateur Rédiger des documentations à l'aide de Dokiel au niveau de l'arborescence de l'atelier, indiquant le contenu sur lequel porte l'erreur, puis sur la page du contenu sélectionné. Soit le contenu de la balise est incomplet, soit l'item sélectionné n'est pas adapté. On trouvera également ce genre d'alerte. Elle signale l'oubli d'une référence dans le corps d'un texte. Onglet gras Un contenu qui n'a pas été enregistré est ouvert dans un onglet dont le titre s'affiche en gras. Enregistrer en cliquant sur. Ci-contre : une section demande à être enregistrée (onglet de gauche) ; une section demande à être corrigée (onglet de droite). Noter en effet la présence de la croix rouge. Vérifier que toutes les sections sont reliées au Guide utilisateur. Il s'agit de relier les sections principales au guide. Dans l'exemple qui suit, le guide semble devoir comporter 4 sections principales. On relève que le guide est signalé en erreur dans l'arborescence. Le problème est au niveau d'une des 4 sections. Dans ce cas précis, elle est bien rattachée au guide mais elle a été supprimée en tant qu'objet de l'arborescence des fichiers. Faire ici un clic droit sur le champ Section et choisir de section. S'il s'agit de remplacer le lien : faire un clic et section qui convient. Rappel : Rattacher une section à un guide Cliquer sur pour afficher Section... Supprimer le lien vers cette Effacer cette référence, puis rattacher la Février 2015 Version : 2.0 Direction des Usages du Numérique 35

36 Rédiger des documentations à l'aide de Dokiel Création d'une documentation utilisateur Double cliquer ensuite sur le. Dans le réseau d'items qui s'affiche alors, choisir, d'un clic gauche, la section qui convient (item «*.scen»). Puis cliquer sur le bouton Sélectionner en bas de page. Vérifier que le Guide utilisateur est rattaché à l'item racine du support papier ou du support web. Rappel : Le Guide utilisateur est un item en «*.pub». Il se trouve, pour les deux supports, en bas de page Générer la création des supports Il est nécessaire ici de finaliser les contenus des deux supports : renseigner les métadonnées, compléter le titre principal. Le travail va s'effectuer en deux temps si l'objectif est de diffuser un guide web qui offre la possibilité au lecteur de télécharger et imprimer la version papier : compléter le support papier pour le générer, le transformer en fichier PDF et le rattacher au guide web ; compléter le guide web pour le générer puis le publier. Le guidepapier Renseigner les métadonnées du support papier. Il ne s'agit pas de contenus à proprement parler mais d'informations sur le document. Certains des éléments qui seront renseignés ici figureront sur la toute première page du document papier. Certains autres seront affichés en pied de page. Cliquer sur item «est en *.pub). guidepapier.pub». (Vous l'avez peut-être renommé, mais l'extension 36 Février 2015 Version : 2.0 Direction des Usages du Numérique

37 Création d'une documentation utilisateur Rédiger des documentations à l'aide de Dokiel Il est nécessaire de renseigner : un champ titre long qui précise le titre principal du guide utilisateur ; Par exemple pour le présent guide (le Guide Dokiel que vous êtes en train de suivre!) : le titre principal est «Guide utilisateur Dokiel» et le titre dit «long» est : «Documentation en ligne pour une aide à l'installation et à la prise en main de la chaîne éditoriale» ; une illustration et le logo de l'application ; la version du document, la date et les informations auteur (dont la licence d'utilisation) ; les informations constituent un bloc qui peut être collé et utilisé dans le guideweb ; l'aide : un item de type «*.scen» qui renseigne le lecteur final notamment sur les coordonnées du support ; elle constitue un des items communs pré-rédigés et proposés à la communauté des utilisateurs de Dokiel. Il suffit de pointer vers cet item pour disposer des contenus à jour. Elle est bien sûr modifiable. Il suffit dans ce cas de créer son propre item d'aide et de copier une partie des contenus (parties ou blocs constitutifs) ; le paramétrage de l'affichage de certaines données : le glossaire par exemple. Lancer la génération du Guide papier Cliquer sur le guidepapier ( item «*.pub») dans l'arborescence des espaces et items. Cliquer sur. Cliquer sur. Attendre quelques instants que la génération se fasse. Pour vérifier le PDF, cliquer sur Février 2015 Version : 2.0 Direction des Usages du Numérique 37

38 Rédiger des documentations à l'aide de Dokiel Création d'une documentation utilisateur Si la génération est effectuée depuis ScenariServer, une authentification est requise. Enregistrer le document sur son ordinateur. Le guideweb Renseigner les métadonnées du support web Les éléments renseignés ici vont être répartis en différentes rubriques. On trouve : 1. Le champ titre long qui complète le titre principal (non obligatoire). 2. Le logo de l'application (non obligatoire). Il apparaîtra au bas de l'arborescence de navigation. Pour information : le logo de l'université est automatiquement inséré à la documentation. 3. Les informations auteur (qui apparaissent ensuite dans la rubrique «A propos», sous l'arborescence de navigation). Elles comportent : la version du document ; la date ; la service ou la composante d'appartenance (il n'est pas utile de préciser Université de Strasbourg, le modèle présente cette information automatiquement) ; le pôle, département, laboratoire de rattachement ; la licence d'utilisation (de type Creative Commons [ - Creative Commons France] ). 4. La version PDF est un item de type (en «*.pdf»). 5. L' aide est un item de type «*.scen». Elle indique les coordonnées du support et les modalités de consultation de la documentation. Elle fait partie des items communs pré-rédigés par l'ipm. Elle est modifiable pour adaptation à vos préférences ou besoins. Il suffit dans ce cas de créer son propre item 38 Février 2015 Version : 2.0 Direction des Usages du Numérique

39 Création d'une documentation utilisateur Rédiger des documentations à l'aide de Dokiel d'aide et de copier une partie des contenus (parties ou blocs constitutifs). Plus bas sur la page, on trouve : 6. le champ Description : en quoi consiste le document, à qui s'adresse-t-il? Double cliquer sur Description. Pour ajouter des éléments de contenus textuels, et structurer en paragraphes, cliquer sur. 7. le GuideUtilisateur, bien sûr! Pour situer tous les éléments renseignés ci-dessus : consulter la rubrique : «L'organisation d'un guide» L'interface d'une documentation web construite avec DOKIEL (cf. L'interface d'une documentation web construite avec DOKIEL ) [p.11] Lancer la génération du support web Cliquer sur le guideweb dans l'arborescence des espaces et items. Rappel : item «*.pub». Cliquer sur. Cliquer sur. Attendre quelques instants que la génération se fasse. Cliquer sur. Si la génération est effectuée depuis ScenariServer, une authentification est requise. Le guide s'ouvre dans une fenêtre de navigateur Diffuser sa documentation Présentation de son guide pour validation avant diffusion Vous souhaitez présenter le contenu produit à des collègues pour contribution ou validation. Présenter le guidepapier Si ces collègues ne disposent pas d'un compte Scenari, il suffit de générer le guide papier et d'enregistrer le fichier PDF sur son ordinateur. Février 2015 Version : 2.0 Direction des Usages du Numérique 39

40 Rédiger des documentations à l'aide de Dokiel Création d'une documentation utilisateur Présenter le guideweb Formule 1 Il est possible de générer le guideweb pour le récupérer sous forme de fichier zip contenant l'ensemble des ressources constitutives de la documentation. Sur la page de publication du guideweb, générer sa documentation puis cliquer sur «télécharger» et enregistrer le «guideweb_gendocguide» sur son ordinateur. Pour présenter le module, il suffit ensuite, à l'intérieur de ce dossier «guideweb_gendocguide», d'ouvrir le fichier «index.html». Les contenus s'ouvrent dans une fenêtre de navigateur. Formule 2 Il est possible d'ouvrir un accès Scenari à tout nouveau contributeur. Contacter le support pour cela. Formule 3 La documentation peut éventuellement être mise en ligne par l'équipe IPM de la DUN. Contacter le support pour cela. Il conviendra ensuite de communiquer l'url de consultation à ses relecteurs. Mise à disposition de sa documentation utilisateur Votre documentation est finalisée et validée. Vous souhaitez à présent la diffuser. Diffusion «autonome» Utiliser le zip tel que récupéré ci-dessus. Mise à disposition de la documentation via l'e.n.t et/ou via le site des services numériques Si la documentation se rapporte à l'une des applications accessibles via l'e.n.t, il est possible de la rattacher au canal de l'application dans l'e.n.t. 40 Février 2015 Version : 2.0 Direction des Usages du Numérique

41 Création d'une documentation utilisateur Rédiger des documentations à l'aide de Dokiel Un d'accès à l'aide en ligne est alors activé. Aide en ligne pour SOSIE - Services d'enseignement Envoyer dans ce cas sa demande à support@unistra.fr pour le département IPM de la DUN. Un espace de stockage de l'ensemble des documentations logicielles de l'université existe. Une rubrique Documentations existe sur le site des Services Numériques. Février 2015 Version : 2.0 Direction des Usages du Numérique 41