Générer la documentation de votre modèle physique de données MySQL

L'outil mysqldump permet d'exporter toute ou une partie de la structure d'une base de données au format XML. De là, il est possible de tansformer ce document, avec une feuille de style XSL, pour générer la documentation de votre modèle physique de données au format HTML.

La solution exposée ici permet de générer une documentation complète de la structure des tables du schéma, en incluant les index, les clés étrangères ainsi que les commentaires des tables et des colonnes.

Rédaction de documentations techniques sur Confluence : partie 2

Et voilà la suite que tout le monde attendait. Aujourd’hui nous verrons comment utiliser les wikis pour publier de la documentation, depuis la création du brouillon jusqu’à la publication !

  • Première chose : contrairement aux idées reçues, les wikis supportent les contenus structurés !

Beaucoup de monde pense que les wikis sont une simple suite de pages aux contenus informes, où vous pouvez seulement établir des liens entre des pages en cliquant sur un lien, un index ou depuis le résultat produit par un outil de recherche. Hé bien non ! Tous les wikis ne sont pas comme ça ! Les « bons wikis » vous permettent de structurer vos pages au sein d’une hiérarchie « parents » / « enfants ». Ce qui permet de développer du contenu comme vous l’entendez, de la même façon que dans un livre avec des parties, des chapitres, des sous-chapitres ou des sous-sections.

Les wikis d’entreprise comme Confluence sont construits autour  des concepts d’espaces. Chaque espace est composé d’une hiérarchie de pages (un peu comme un mini site Web) avec ses propres permissions. On peut utiliser les espaces de Confluence pour stocker les informations de chacun des produits, éditions, versions d’une série de documentation spécifique. Confluence permet également de réutiliser élégamment un contenu entre des espaces, et de lier des pages au sein d’espaces différents.

Pour présenter votre documentation, vous pouvez utiliser le thème ‘Confluence Documentation’. Il peut être appliqué à n’importe quel espace au sein d’un site. Il fournit une interface de type ’aide en ligne’. Vous pouvez même ajouter un outil de recherche dans la colonne de gauche, ce qui restreint vos recherches à une hiérarchie précise de pages, et évite de vous encombrer de réponses non désirées. Ce thème vous permet de maintenir votre propre documentation structurée et aide vos lecteurs à trouver ce qu’ils cherchent sans perdre de temps.

  • Pourquoi les wikis sont-ils idéals pour la documentation collaborative ?

Les wikis permettent de réaliser des brouillons, des avant-projets ; vous avez la possibilité de les faire relire par des collègues avant de les publier auprès d’une audience plus large et / ou de l’audience finale.

Il est possible d’appliquer des restrictions en visualisation et en modification aux pages de manière à ce que des collaborateurs spécifiques ou groupes de collaborateurs puissent voir, éditer ou commenter vos brouillons. Au sein de Confluence, vous pouvez déterminer qui peut éditer votre page et qui peut y laisser des commentaires. Vous pouvez récupérer les feedbacks des visiteurs via les commentaires laissés en bas de pages sans que ces personnes aient forcément accès à la modification du contenu.

Pour faciliter la collaboration dans vos processus de révision vous pouvez :

-          Choisir de recevoir des notifications (via des emails et / ou des flux RSS) quand une page spécifique ou quand n’importe quel contenu est modifié au sein d’un espace,

-          Suivre l’activité des autres utilisateurs afin de surveiller les modifications et les commentaires de chaque page,

-          Mettre à jour votre statut actuel afin de permettre aux autres utilisateurs de voir ce sur quoi vous êtes en train de travailler,

-          Impliquer vos lecteurs en leur permettant de contribuer au contenu via les commentaires.

La capacité de pouvoir structurer vos contenus comme dans un livre et la collaboration de chacun au contenu permettent de faciliter la création, la révision et la publication de vos documents. C’est donc bien cela, les wikis sont idéals pour qui est partisan du travail collaboratif !

  • Comment écrire, mettre à jour et publier du contenu dans un wiki ?

Si vous étiez sur le point d’écrire du contenu dans un nouveau wiki ou un nouvel espace, vous commenceriez normalement par créer une page racine et vous lui ajouteriez des pages enfants. Pour les nouvelles éditions / versions de votre documentation déjà existante, le plus commun des scénarios serait de mettre à jour votre contenu.

Mettre à jour un contenu qui existe déjà :

Atlassian utilise un site Confluence public pour écrire sa documentation produit. Chaque version de produits y a son propre espace. La mise à jour se fait systématiquement dès qu’une nouvelle version de produit est publiée, en réalisant les brouillons de ces mises à jour dans l’espace « live » de la nouvelle version du produit. Confluence permet effectivement de copier des espaces entiers via le plugin ‘Copy Space’, alors pourquoi se priver ? Autant en créer un nouveau, en faisant en sorte qu’il ne soit pas présenté aux visiteurs ! Vous avez ainsi la possibilité de maximiser sa pertinence en permettant à vos collègues d’améliorer le contenu dans l’espace de la version de produit en cours de développement. Si le contenu en cours de mise à jour était dans un espace complètement caché, vous manqueriez l’opportunité de collecter ces petites améliorations.

Alors, comment mettre à jour un contenu au sein d’un espace wiki « live » ? Il y a deux façons de mettre à jour le contenu de pages : en créant une nouvelle page ou en complétant une page existante. Pour les créations, il faut simplement ajouter une page, y appliquer les restrictions en lecture et en édition nécessaires et commencer à renseigner son contenu. Pour les pages modifiées, il faut afficher la page de départ et en créer une copie. Le contenu de cette page fille est identique à celui de son parent. Il faut ensuite appliquer les restrictions de lecture et d’édition à la copie de la page et commencer à modifier son contenu.

Publier vos mises à jour

Après avoir mis à jour vos brouillons dans votre espace wiki « live », vous avez besoin de le publier. Pour les nouvelles pages, la procédure est très simple : vous avez juste à modifier les restrictions de lecture de la page et celle-ci sera publiée ! Pour les pages qui ont été révisées, les choses sont un petit peu plus complexe. En général, on copie les mises à jour de contenus de la page enfant et on les colle dans la page parent. Nous n’avons plus besoin de la page enfant, elle peut être détruite.

Que se passe-t-il si quelqu’un a fait une mise à jour après que vous ayez fait votre copie en vue de modifier le contenu ? Si cette mise à jour est importante dans le cadre de votre révision, vous devez l’incorporer dans la copie de la page enfant avant de commencer à publier la page en question. Si l’on suspecte que la page contient une modification qui n’aurait pas été capturée au moment de la copie, il faut vérifier la dernière date de publication de la page parent pour être sur. Heureusement cela n’arrive pas très souvent.

Voilà, c’était le deuxième billet de cette saga spéciale, j’espère qu’il vous a plu ?! Suite au prochain numéro !

bouton_atlassian_netapsys