La base de connaissances: Votre meilleur ami en tant qu'écrivain technique

Vous connaissez le sentiment d'être devant une montagne d'informations et de ne pas savoir par où commencer.
En tant qu’auteur technique, c’est votre «pain quotidien».

Mais que se passerait-il si vous aviez un outil pour vous aider à vaincre cette montagne? C’est précisément de cela qu’il s’agit aujourd’hui: Nous plongeons dans le monde des bases de connaissances et voyons comment elles vous soutiennent dans votre travail d'écrivain technique.

Une base de connaissances est comme un cerveau numérique pour votre entreprise, votre équipe et/ou vos projets. Elle rassemble, structure et conserve toutes les connaissances dont vous avez besoin pour créer votre documentation. Des spécifications techniques aux instructions en passant par les arrière-plans, vous trouverez tout en un seul endroit. Cela permet non seulement de gagner du temps, mais aussi de s'assurer que vos documents sont toujours précis et à jour. Si quelqu'un s'occupe d'elle. ⁇

Qu'est-ce qu'une base de connaissances?

Imaginez une base de connaissances comme une sorte d'archive centrale. Il s'agit d'une collection d'informations disponibles sous une forme organisée et consultable. Ce qui est spécial à ce sujet: Elle est accessible à tous dans l'équipe.

L'idée derrière cela: Qu'il s'agisse des dernières fonctionnalités du produit, des bons termes ou des erreurs courantes, au lieu d'envoyer un e-mail pour chaque problème ou de fouiller dans les anciens chats, il suffit de regarder dans la base de données. Cela vous rend non seulement plus efficace, mais aussi de véritables gestionnaires de connaissances.

Spécifications techniques: Le cœur de votre travail

Lors de la création d'une base de connaissances, les spécifications techniques sont l'essentiel. Ici, vous recueillez tous les détails importants sur les produits ou systèmes sur lesquels vous écrivez. Pensez à des choses comme:

Diagrammes d'architecture: Comment les différents composants sont-ils liés?
Documentation de l'API: Quels sont les points de terminaison et comment fonctionnent-ils?
Descriptions des fonctions: Qu'est-ce que le produit et quelle est la logique derrière cela?

En stockant ces informations de manière centralisée, vous vous assurez que tous ceux qui travaillent sur la documentation sont sur la même longueur d'onde. Cela permet d'éviter les erreurs et d'économiser un nombre infini de tours de vote.

Les bons outils pour votre base de connaissances

Votre succès dans la création d'une base de connaissances dépend en grande partie des bons outils. En fonction de la taille du projet et du flux de travail de l'équipe, il existe différentes solutions qui vous conviennent. Certains outils s'appuient sur des langages de balisage simples tels que Markdown, tandis que d'autres, en tant que solutions tout-en-un, couvrent toutes les étapes de la documentation.

Les outils bureautiques courants tels que Word/Google Docs/Notepad++ vous aident à écrire, mais sont ensuite stockés quelque part sous forme de fichiers individuels et une recherche sur divers documents ne serait pas idéale. Pour une meilleure visualisation, on utilise souvent des outils du portefeuille Adobe (Illustrator, Photoshop, InDesign, etc.) Mais tout cela doit être stocké de la manière la plus cohérente, structurée et accessible possible, de sorte que plus tard, idéalement, il n'est plus nécessaire de faire beaucoup d'efforts pour fournir ce contenu aux utilisateurs.

Examinons donc quelques-unes des options les plus courantes que les rédacteurs techniques peuvent prendre en charge aujourd'hui.

1. Markdown & Docs-as-Code

Qu'est-ce que c'est? Markdown est un langage de balisage extrêmement simple et intuitif. Vous écrivez vos textes avec un formatage minimal dans des fichiers texte simples, puis vous pouvez les convertir en HTML. En combinaison avec un système de contrôle de version tel que Git, il s’agit de la base d’une approche «docs-as-code», dans laquelle la documentation est traitée comme un logiciel.
Avantages:
- Simple et rapide: Markdown est si simple que tout le monde le comprend immédiatement. Idéal pour les notes courtes et rapides ou les documents sur lesquels les développeurs travaillent également.
- Contrôle de version: Chaque changement fait l'objet d'un suivi. Vous voyez toujours qui a changé quoi et quand, et vous pouvez revenir à une version précédente si nécessaire.
- Collaboration: Les développeurs et les rédacteurs techniques peuvent travailler ensemble dans le même environnement (par exemple, Git).
Inconvénients:
- Formatage limité: Pour les mises en page complexes, les tableaux ou les mises en forme spéciales, Markdown n'est souvent pas suffisant.
- Pas de gestion centralisée: Sans outils supplémentaires (comme un générateur de site Web statique), il est difficile de gérer une base de connaissances complexe.

Markdown Tools est disponible sur presque toutes les plateformes et dans différentes variantes:

Mac: MacDown, iA Writer, ou Marked 2 iOS / Android: iA Writer Windows : ghostwriter ou Monstre de Markdown Linux : ReText ou encore le ghostwriter Site web: Dillinger ou StackEdit

2. AsciiDoc & Docs-as-Code

Qu'est-ce que c'est? AsciiDoc est une alternative plus puissante à Markdown. C'est également un langage de balisage simple, mais qui offre beaucoup plus de fonctionnalités pour la documentation technique. Encore une fois, l'idée est d'écrire la documentation dans des fichiers texte et de la gérer via des systèmes de contrôle de version.
Avantages:
- Syntaxe complète: AsciiDoc prend en charge des fonctions telles que les références croisées, les variables, les textes conditionnels et les tableaux complexes. Idéal pour une documentation professionnelle et complète.
- Réutilisabilité: Vous pouvez définir des blocs de texte (par exemple, une consigne de sécurité) en un seul endroit et les réutiliser dans de nombreux documents. Cela permet de gagner du temps et d'assurer la cohérence.
- Flexible: Les fichiers texte peuvent être exportés dans différents formats (HTML, PDF, EPUB).
Inconvénients:
- Courbe d'apprentissage: L'entrée est un peu plus difficile que Markdown, car la syntaxe est plus complexe.
- Pas de WYSIWYG: Vous ne voyez pas directement à quoi ressemble le résultat final, mais vous devez d'abord compiler le document.

Aussi pour AsciiDoc il existe différents outils / outils répartis sur toutes les plates-formes: Linux, Mac et Windows Les utilisateurs peuvent tous asciidoctor, SciTE ou AsciiDocFX Recourir à ce qui Projet AwesomeAsciiDoc Github Mais il répertorie également les plugins, les outils et tout ce que votre cœur désire.

3. DITA & le DITA Open Toolkit

Qu'est-ce que c'est? DITA (Darwin Information Typing Architecture) est une Norme basée sur XML pour l'élaboration et la publication de la documentation technique. Il s'agit d'une approche structurée basée sur l'idée de Topics (petites unités d'information réutilisables). Ces topics sont présentés dans une Carte de DITA qui définit la structure de votre documentation. Le DITA Open Toolkit (DITA-OT) est au cœur du système, un moteur de publication open source qui convertit les fichiers DITA en différents formats de sortie tels que PDF, HTML, etc. Des outils comme le oXygen XML Editor offrent une interface intuitive pour créer des fichiers DITA et utiliser le DITA-OT.
Avantages:
- Réutilisabilité maximale: Les topics une fois écrits peuvent être réutilisés dans d'innombrables documents. C'est idéal pour les lignes de produits ou les documents comportant de nombreuses sections similaires.
- Cohérence et standardisation: La structure stricte garantit la qualité et l'uniformité de la documentation.
- Séparation du contenu et du format: Vous vous concentrez uniquement sur le contenu. La mise en page est ensuite définie par le DITA-OT. Ainsi, vous pouvez générer un document en un clic pour l'aide en ligne ou sous forme de manuel PDF.
Inconvénients:
- Grande complexité et courbe d'apprentissage: L'entrée dans DITA et XML nécessite du temps et une formation spécialisée. Ce n'est certainement pas un projet rapide.
- Coûts élevés: Les éditeurs XML professionnels, qui sont pratiquement indispensables pour travailler efficacement avec DITA, sont généralement payants.

En guise d'exemple payant, je cite Framemaker d'Adobe ou oXygen, sur le site open source/freeware je tombe Codex un. Grâce au standard XML ouvert et à la boîte à outils, tout le monde peut également utiliser OpenJDK comme Amazon Corretto ou Azul Zulu Fabriquer son propre soubassement.

4. Document360

Qu'est-ce que c'est? Document360 est une plate-forme moderne de base de connaissances basée sur le cloud spécialement conçue pour la création d'aide en ligne, de portails en libre-service et de bases de connaissances internes.
Avantages:
- Solution tout-en-un: De la création à la publication en passant par l'analyse du comportement des utilisateurs, tout est réuni dans un seul outil.
- Facilité d'utilisation: L'interface utilisateur est intuitive et facile à utiliser, même pour les non-techniciens. L'éditeur prend en charge Markdown, ce qui permet un démarrage rapide.
- Outils d'analyse: Vous pouvez voir quels articles sont lus, quels termes de recherche les utilisateurs utilisent et où il y a des lacunes dans les connaissances. Cela vous aidera à améliorer continuellement votre documentation.
Inconvénients:
- Coûts : En tant que solution SaaS (Software-as-a-Service), des frais mensuels ou annuels sont facturés, qui varient en fonction de la taille de l'équipe.
- Dépendance: Vous êtes lié à la plate-forme et vous ne pouvez pas simplement traiter le contenu dans un autre outil.

Il s’agit: une plate-forme ClosedSource autonome, avec tous les avantages et inconvénients correspondants. Interfaces avec pratiquement tous les helpdesk et outils de collaboration mais sont présents, l'intégration dans Techstack existant n'est donc pas un obstacle majeur.

5. Adobe RoboHelp

Qu'est-ce que c'est? RoboHelp est un outil de création d'aide (HAT) classique et très bien établi d'Adobe. C'est un outil de bureau qui permet de créer de l'aide en ligne, des bases de connaissances et bien plus encore.
Avantages:
- Fonctionnalités étendues: RoboHelp offre tout ce que le cœur de Technical Writer désire: de la réutilisation du contenu à la gestion des variables, en passant par les mises en page complexes.
- Intégration: Il s'intègre facilement avec d'autres produits Adobe et des systèmes externes.
- Base stable: En tant que produit durable, il a une grande communauté et est très mature.
Inconvénients:
- Complexité: En raison des nombreuses fonctionnalités, l'entrée peut être écrasante.
- Coûts : RoboHelp est également un outil payant qui représente un investissement.

Le grand-père parmi les outils, Adobe Robohelp En fait, cette énumération n'est pas tout à fait correcte. Néanmoins, et précisément parce qu'il est extrêmement volumineux et qu'il est également à l'avant-garde de nombreux autres outils en raison de son âge, il ne devrait pas être ignoré.

Instructions et processus: Votre guide

Une bonne base de connaissances contient non seulement des informations statiques, mais aussi des instructions et des processus dynamiques. Cela peut être, par exemple:

Instructions d'intégration: Comment initiez-vous les nouveaux membres de l'équipe au travail?
Guides de style: Quelles règles s'appliquent à la langue, au formatage et à la terminologie de vos documents?
Flux de travail: Comment se déroule le processus, de la recherche à la publication d'un document?

De tels guides vous aideront non seulement vous, mais aussi d'autres équipes. L'équipe d'assistance peut s'impliquer rapidement, les développeurs peuvent voir comment ils donnent leur avis et même les nouveaux collègues peuvent se débrouiller beaucoup plus rapidement. Cela rend votre travail plus transparent et votre équipe plus agile.

L'histoire d'un Technical Writer

En tant qu'auteur technique, vous êtes le médiateur entre les experts et les utilisateurs. Vous avez la capacité unique d'expliquer des faits complexes de manière à ce qu'ils soient compréhensibles pour tout le monde. Une base de connaissances est votre allié le plus puissant, car elle vous aide à remplir parfaitement ce rôle d'intermédiaire.

En rassemblant les connaissances dans l'entreprise, vous voyez où il y a des lacunes et où vous devez commencer. Vous reconnaissez les points de douleur des utilisateurs et pouvez les aborder de manière ciblée dans votre documentation. Une base de connaissances bien entretenue n'est donc pas seulement un référentiel d'informations, mais aussi un reflet de votre propre expertise et de votre valeur pour l'entreprise. Elle montre que vous ne vous contentez pas d'écrire, mais que vous rendez toutes les connaissances de l'entreprise structurées et accessibles.

Conclusion: Pas seulement un outil, mais un super-pouvoir

Une base de connaissances est bien plus qu'un simple outil. C'est une décision stratégique qui vous rendra plus efficace, plus transparent et meilleur en tant qu'écrivain technique et toute votre équipe. En centralisant la connaissance, vous pouvez vous concentrer sur ce que vous faites le mieux: Communiquer des sujets complexes de manière simple et claire.

TL:DR

Commencez à rassembler et à structurer vos connaissances. Ça vaut le coup!