Les équipes chargées des produits et les équipes chargées des logiciels ont toutes deux un problème commun : la documentation.
La documentation produit fait référence aux manuels et guides destinés à l'utilisateur qui expliquent le déroulement des opérations et l'interface utilisateur d'un produit. Comment l'utilisateur moyen peut-il être productif avec ce produit ? En ce sens, la documentation produit pourrait être utilisée pour les produits logiciels.
La documentation sur les logiciels fait référence aux technologies sous-jacentes, aux conditions préalables et aux attributs configurables d'un produit logiciel. Comment les administrateurs informatiques configurent-ils, surveillent-ils, hébergent-ils et déploient-ils le produit logiciel pour les utilisateurs ? Ce type de documentation est important, en particulier lorsque plusieurs versions ou branches sont ajoutées au mélange.
D'une certaine manière, la documentation d'un produit revient à apprendre à quelqu'un à conduire une voiture. La roue fait tourner la voiture, la pédale d'accélérateur la fait avancer, la pédale de frein l'arrête. La documentation du logiciel enseigne à quelqu'un comment fonctionne la voiture. La roue est reliée à l'essieu avant qui fait tourner les pneus avant pour modifier la trajectoire ; l'accélérateur augmente le flux d'air vers le moteur qui aspire plus de carburant, générant ainsi du couple et de la puissance.
Les deux types de documentation sont importants. L'un éduque les utilisateurs, l'autre les administrateurs et les développeurs. C'est bien de montrer aux gens comment conduire une voiture, mais si personne ne sait comment fonctionne la voiture, que se passera-t-il lorsqu'elle tombera en panne ?
Différences mineures entre la documentation d'un produit et celle d'un logiciel
Il existe des différences mineures entre la documentation d'un produit et celle d'un logiciel :
Documentation sur les logiciels et les produits : Public cible et persona
La documentation produit s'adresse à un seul public : l'utilisateur. Elle part du principe que l'utilisateur n'a aucune connaissance technique et communique dans un anglais simple, avec un minimum de jargon. À l'instar d'un apprentissage technique par rapport à un diplôme universitaire, elle enseigne aux gens comment faire les choses, en mettant moins l'accent sur les connaissances théoriques ou conceptuelles.
La documentation sur les logiciels s'adresse aux administrateurs informatiques, aux ingénieurs et aux développeurs. Elle couvre la conception et l'architecture du logiciel, les instructions de configuration de la ligne de commande, l'API et le support d'intégration, la gestion des données et les rapports, la topologie du réseau - en gros, les rouages qui font fonctionner la machine. Ces documents constituent une source unique de vérité (SSOT) à laquelle le personnel informatique peut se référer lors du contrôle et du dépannage de l'application logicielle.
Documentation sur les logiciels et les produits : Fréquences de mise à jour
La documentation du logiciel doit être mise à jour de manière cohérente au fur et à mesure que de nouvelles versions sont intégrées dans le canal de diffusion principal. La documentation du logiciel doit mettre en évidence les nouvelles fonctions et commandes, et supprimer les anciennes fonctionnalités. Les dépendances nouvelles ou changeantes doivent être documentées, et la prise en charge des fonctionnalités sur toutes les plateformes cibles doit être clarifiée - par exemple, une fonctionnalité fonctionne sous Windows, mais pas sous Linux.
La documentation du produit ne doit être mise à jour que lorsque les modifications du logiciel sous-jacent entraînent un changement dans le flux de travail ou la facilité d'utilisation. Un développeur modifie le code d'une passerelle de paiement, mais le processus de paiement pour les utilisateurs reste le même, de sorte qu'aucune mise à jour n'est nécessaire.
Cela montre une hiérarchie naturelle pour la documentation des produits logiciels. La documentation technique du logiciel constitue la base, et la documentation ultérieure du produit est basée sur cette base. Par conséquent, l'accent doit être mis sur l'élaboration d'une documentation logicielle de qualité, car elle donne naissance à une documentation produit encore meilleure.
Exemples de cadres de formatage pour la documentation sur les produits et les logiciels
Une documentation sur un produit pourrait suivre ce cadre :
-
Nom du produit
-
Aperçu de l'objectif du produit
-
*Guide d'installation
Caractéristiques 1 - Explications et images
Caractéristiques 2 - Explications et images
*Liens d'assistance à la clientèle
De même, une documentation sur un logiciel pourrait suivre ce cadre :
-
Nom du logiciel
-
Aperçu de l'objectif du logiciel
-
*Dépendances du logiciel
-
Guide d'installation
Explication de la fonction 1 et images
Explication de la fonction 2 et images
*Liens d'assistance technique
Il est clair que ces deux types de documentation sont étroitement liés l'un à l'autre et suivent une structure similaire. Cela signifie que les équipes chargées des produits et des logiciels ont beaucoup à apprendre les unes des autres, et qu'elles ont beaucoup de potentiel lorsqu'elles travaillent en collaboration sur la documentation.
Les équipes chargées de la documentation des produits et des logiciels peuvent se compléter
Il existe de grandes similitudes entre la documentation produit et la documentation logicielle. La question qui se pose est donc la suivante : les équipes chargées des produits et des logiciels peuvent-elles travailler ensemble ?
Oui, c'est possible, et c'est même souhaitable !
Les équipes chargées des logiciels comprennent le jargon technique et les technologies sous-jacentes. Les équipes produits comprennent ce que les utilisateurs voient, ce qu'ils veulent et ce dont ils ont besoin ; l'expérience de l'utilisateur. Les rédacteurs de la documentation logicielle peuvent fournir des informations techniques détaillées, et les rédacteurs de la documentation produit peuvent diluer les détails techniques pour les rendre accessibles à un public non initié.
Imaginez que vous essayez d'expliquer quelque chose en termes simples, sans avoir les connaissances de haut niveau nécessaires pour formuler quelque chose qu'un profane comprendrait. C'est ce qui se passe lorsque la documentation produit est créée avant la documentation logicielle.
Qu'est-ce que la mécanique quantique ? Le chat de Schrodinger est probablement la première idée qui vous vient à l'esprit ! Mais quel est le rapport entre la mécanique quantique et les chats ? Pour l'utilisateur, ce n'est pas important. Pour un physicien, c'est tout.
Commencer par la documentation du logiciel, finir par une meilleure documentation du produit dans Docsie
En conclusion, l'utilisation de la documentation d'un logiciel comme modèle pour la documentation ultérieure d'un produit présente de nombreux avantages. La documentation du logiciel doit servir de source unique de vérité pour le personnel informatique et les rédacteurs de la documentation produit. Une fois la documentation rédigée, les rédacteurs de la documentation produit disposeront de la clarté et de la compréhension nécessaires pour simplifier et partager des connaissances conviviales avec les clients, avec des conseils techniques pour la relecture et l'assurance qualité.
Simplement, en commençant par une excellente documentation logicielle, vos rédacteurs peuvent créer une documentation produit encore meilleure !
Commencez à créer une documentation qui aide vos clients à en faire plus. Inscrivez-vous à notre plan de démarrage (forever free !) et créez une documentation de qualité avec Docsie !