L’image de présentation présente OpenDocs comme un lieu pour créer des diagrammes, documenter ensemble, organiser les connaissances et partager ou publier les résultats. Une méthode utile pour l’utiliser consiste à considérer chaque document comme faisant partie d’une base de connaissances entretenue, et non comme un fichier ponctuel.
OpenDocs est décrit comme un environnement web de gestion des connaissances et de documentation qui rassemble le contenu écrit et les modèles visuels. Le Pipeline de Visual Paradigm peut également connecter les diagrammes créés dans Visual Paradigm Desktop ou Online à OpenDocs, réduisant ainsi la dépendance aux images statiques exportées manuellement. Les fonctionnalités disponibles peuvent dépendre de votre édition et de votre configuration de Visual Paradigm.
1. Planifier la base de connaissances
Avant de rédiger des pages, décidez de l’objectif de l’espace et de ses utilisateurs. Une structure ciblée facilite la recherche et la maintenance de l’information.
Par exemple, une base de connaissances produit ou système pourrait être organisée comme suit :
-
Aperçu — objectif, périmètre, propriétaires et liens vers les pages clés
-
Architecture — contexte du système, composants, intégrations et déploiement
-
Processus — flux de travail, procédures et points de décision
-
Données — entités, flux de données et définitions
-
Opérations — livres de procédures, surveillance, récupération et contacts de support
-
Décisions — choix de conception, justifications et conséquences
-
Glossaire — terminologie partagée et acronymes
Gardez le niveau supérieur compact. Placez les détails dans des sous-pages ciblées et liez les pages entre elles.
2. Créer une page d’aperçu claire
Commencez par une page qui aide un nouveau lecteur à s’orienter. Incluez :
-
Objectif : Ce que couvre cette base de connaissances.
-
Public : Qui devrait l’utiliser.
-
Périmètre : Ce qui est inclus — et, si utile, ce qui ne l’est pas.
-
Propriété : Qui maintient le contenu.
-
Navigation : Liens vers les sections les plus importantes.
-
Actualité : Une date de révision ou des directives pour signaler un contenu obsolète.
Écrivez pour des lecteurs qui ne connaissent pas déjà le projet. Développez les abréviations peu courantes et expliquez le contexte derrière les diagrammes importants.
3. Ébaucher et structurer le contenu
OpenDocs prend en charge la rédaction de documentation et le contenu visuel dans le même espace de travail. Les résultats de recherche décrivent un éditeur orienté Markdown et, dans certains flux de travail, une expérience d’édition WYSIWYG ; utilisez le mode d’édition disponible dans votre compte.
Un modèle de page fiable est :
-
Résumé : Le point clé en quelques phrases.
-
Contexte : Pourquoi le sujet est important et quelles hypothèses s’appliquent.
-
Visuel : Un diagramme qui explique la structure, le comportement ou les relations.
-
Détails : Définitions, étapes, règles ou explications de soutien.
-
Pages liées : Liens vers les prérequis et le matériel de suivi.
-
Propriétaire et date de révision : Qui vérifie la page et quand.
Préférez des titres descriptifs, des paragraphes courts et des listes pour les procédures. Utilisez des tableaux lorsque les lecteurs doivent comparer des champs ou parcourir des faits structurés. Évitez de faire porter à un diagramme des informations que le texte n’explique jamais.
4. Choisir des diagrammes qui répondent à une question
Choisissez un modèle visuel en fonction du problème que vous souhaitez que le lecteur comprenne :
-
Diagramme de flux ou BPMN : Que se passe-t-il, et dans quel ordre ?
-
Diagramme de cas d’utilisation UML ou diagramme d’activité : Qui interagit avec le système, et quel comportement se produit ?
-
Diagramme de composants ou de déploiement UML :Quelles sont les parties, et comment sont-elles disposées ?
-
Diagramme de séquence :Comment les participants communiquent-ils au fil du temps ?
-
MCD :Quelles entités de données existent, et comment sont-elles liées ?
-
Carte mentale ou carte conceptuelle :Comment les idées sont-elles regroupées et connectées ?
-
Diagramme de Gantt, feuille de route ou structure de découpage du travail :Quel travail est prévu, et comment s’articule-t-il ?
Les documents de Visual Paradigm décrivent les flux de travail OpenDocs impliquant des types de diagrammes tels que UML, BPMN, MCD, cartes mentales et visuels de planification de projet. Confirmez qu’un type de diagramme particulier est disponible dans votre édition avant de construire un processus autour de celui-ci.
Donnez à chaque diagramme un titre et une brève explication. Définissez les abréviations, étiquetez les limites importantes et gardez un niveau de détail approprié pour le public. Si un diagramme devient difficile à lire, divisez-le en une vue de haut niveau et une ou plusieurs vues détaillées.
5. Ajoutez des diagrammes à la documentation
L’image de vue d’ensemble suggère un cycle de rédaction simple : créer un visuel, le placer là où il soutient le texte, et expliquer comment le lire.
Une séquence pratique est :
-
Écrivez d’abord l’explication environnante, afin que le diagramme ait un objectif clair.
-
Créez le diagramme dans l’éditeur ou l’outil de modélisation dont vous disposez.
-
Insérez-le ou intégrez-le dans la page pertinente en utilisant l’intégration disponible pour votre compte.
-
Ajoutez une légende ou un texte à proximité décrivant sa portée et son message clé.
-
Vérifiez que les étiquettes sont lisibles à la largeur de page que les lecteurs utiliseront.
-
Revuez la page en tant que lecteur, pas seulement dans la vue d’édition.
Lorsque les diagrammes sont envoyés via le Pipeline de Visual Paradigm, les sources décrivent un flux de travail pour rendre les artefacts de modèle disponibles pour OpenDocs et les sélectionner pour une utilisation dans les documents. Cela peut aider à réduire les copies obsolètes, mais les équipes doivent toujours vérifier que l’artefact intégré pointe vers le modèle et la révision prévus.
6. Collaborez avec un processus de révision léger
Utilisez un processus cohérent afin que la collaboration améliore la précision plutôt que de créer des modifications conflictuelles :
-
Attribuez les responsabilités :Nommez un propriétaire pour chaque page ou section importante.
-
Brouillon :Rédigez le contenu et incluez les visuels nécessaires pour l’expliquer.
-
Revue :Demandez à un expert du domaine de vérifier l’exactitude et à un lecteur extérieur à l’équipe immédiate de vérifier la clarté.
-
Résoudre les modifications :Se mettre d’accord sur les modifications du texte et des diagrammes.
-
Publier ou partager :Rendre la version révisée disponible pour le public visé.
-
Revisiter :Réviser la page lorsque le système ou le processus change.
L’image illustre la collaboration d’équipe, mais les contrôles et la disponibilité exacts de la collaboration peuvent varier. Vérifiez les contrôles affichés dans votre espace de travail OpenDocs plutôt que de supposer que tous les comptes prennent en charge les mêmes options de partage ou d’édition.
7. Organiser et maintenir la base de connaissances
Une bonne base de connaissances nécessite des soins continus. Gardez les pages suffisamment courtes pour être parcourues, utilisez des titres cohérents et liez les sujets connexes au lieu de dupliquer la même explication à plusieurs endroits.
Pour chaque page importante, suivez :
-
Un propriétaire clair
-
Le public visé
-
La source de vérité pour les modèles ou données liés
-
La date de la dernière révision
-
Toutes les limitations connues ou les questions non résolues
Lorsqu’un diagramme change, révisez également le texte qui l’entoure. L’image peut être à jour tandis que l’explication, la terminologie ou la procédure liée ne l’est pas.
8. Partager ou publier avec réflexion
Avant de partager une page ou un espace, vérifiez :
-
Si le public visé peut y accéder
-
Si le contenu inclut des informations sensibles ou réservées à l’interne
-
Si la vue partagée affiche les diagrammes et la mise en page comme prévu
-
Si un destinataire a besoin d’une seule page ou de l’ensemble de la base de connaissances
-
Si le matériel est prêt pour des lecteurs externes
Les options exactes de partage et de publication dépendent du compte et de la configuration. Considérez l’étape « Partager » de l’image de présentation comme un objectif de flux de travail, et non comme une garantie d’une destination de publication particulière ou d’un modèle de permissions.
9. Une liste de vérification de page réutilisable
Avant de considérer une page prête, confirmez qu’elle :
-
A un titre et un objectif clairs
-
A du sens pour son public visé
-
Définit les termes peu familiers
-
Utilise des diagrammes qui répondent à des questions spécifiques
-
Explique les visuels importants dans le texte
-
Lien vers des pages connexes et des documents sources
-
Identifie un propriétaire et une date de révision
-
A été vérifié dans sa vue partagée ou destinée aux lecteurs
Exemple de flux de travail
Pour documenter un nouveau service, commencez par une page de présentation qui explique son objectif et sa propriété. Ajoutez un diagramme de contexte du système pour montrer ses utilisateurs et ses dépendances externes. Créez un diagramme de composants pour ses parties principales, puis documentez les flux de requêtes clés et les procédures opérationnelles sur des pages distinctes. Liez les pages depuis la page de présentation, réexaminez-les avec l’équipe du service, et partagez la vue appropriée avec le public cible. Si le modèle sous-jacent change, mettez à jour ou revérifiez le visuel lié et son explication.
Le principe central est simple : maintenez la connexion entre l’écriture, les diagrammes, l’organisation et le processus de partageC’est ce qui transforme une collection de pages et de visuels en une documentation utile et maintenable.
Cette publication est également disponible en Deutsch, English, Español, فارسی, Bahasa Indonesia, 日本語, Polski, Portuguese, Ру́сский, Việt Nam, 简体中文 : liste des langues séparées par une virgule, 繁體中文 : dernière langue.