Les équipes produit et logiciel face à un ennemi commun : la documentation¶

Les équipes produit et les équipes logiciel partagent un même défi : la documentation.

La documentation produit désigne les manuels et guides destinés aux utilisateurs qui expliquent le fonctionnement et l'interface d'un produit. Comment l'utilisateur moyen peut-il être productif avec ce produit ? Dans ce sens, la documentation produit peut s'appliquer aux produits logiciels.

La documentation logicielle concerne les technologies sous-jacentes, les prérequis et les 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 crucial, surtout lorsque plusieurs versions ou branches entrent en jeu.

En quelque sorte, la documentation produit revient à enseigner à quelqu'un comment conduire une voiture. Le volant dirige la voiture, l'accélérateur la fait avancer, le frein l'arrête. La documentation logicielle, elle, explique comment fonctionne la voiture. Le volant est relié à l'essieu avant qui fait tourner les roues pour changer la direction ; l'accélérateur augmente le flux d'air vers le moteur qui consomme plus de carburant, générant couple et puissance.

Ces deux types de documentation sont essentiels. L'un forme les utilisateurs, l'autre forme les administrateurs et développeurs. C'est bien d'apprendre aux gens à conduire une voiture, mais si personne ne sait comment elle fonctionne, que se passe-t-il quand elle tombe en panne ?

Différences mineures entre documentation produit et logicielle¶

Voici quelques différences importantes entre la documentation produit et logicielle :

Documentation logicielle et produit : public cible et persona¶

La documentation produit s'adresse à un public unique : l'utilisateur. Elle part du principe que l'utilisateur n'a aucune connaissance technique, communiquant en langage simple avec un minimum de jargon. Comme un apprentissage technique comparé à un diplôme universitaire, elle apprend aux gens comment faire les choses, avec moins d'accent sur les connaissances théoriques ou conceptuelles.

La documentation logicielle cible les administrateurs informatiques, ingénieurs et développeurs. Elle couvre la conception et l'architecture du logiciel, les instructions de configuration en ligne de commande, le support d'API et d'intégration, la gestion des données et les rapports, la topologie réseau – fondamentalement les rouages qui font fonctionner la machine. Ces documents constituent une source unique de vérité (SSOT) que le personnel informatique peut consulter lors de la surveillance et du dépannage de l'application.

Documentation logicielle et produit : fréquence des mises à jour¶

La documentation logicielle doit être constamment mise à jour à mesure que de nouveaux commits sont fusionnés dans le canal de diffusion principal. Elle doit mettre en évidence les nouvelles fonctions et commandes, et signaler les fonctionnalités obsolètes. Les dépendances nouvelles ou modifiées doivent être documentées, et la prise en charge des fonctionnalités sur toutes les plateformes cibles doit être clarifiée – comme une fonctionnalité qui fonctionne sur Windows, mais pas sur Linux.

La documentation produit ne nécessite des mises à jour que lorsque des modifications logicielles sous-jacentes entraînent un changement dans le flux de travail ou l'utilisabilité. Un développeur modifie le code d'une passerelle de paiement, mais le processus de paiement pour les utilisateurs reste le même, donc aucune mise à jour n'est nécessaire.

Cela révèle une hiérarchie naturelle pour la documentation de produits logiciels. La documentation technique forme la base, et la documentation produit qui en découle repose sur cette fondation. L'accent devrait donc être mis sur la création d'une excellente documentation logicielle, car elle engendre une documentation produit encore meilleure.

Exemples de structures pour la documentation produit et logicielle¶

Une documentation produit pourrait suivre cette structure :

• Nom du produit
• Aperçu de l'objectif du produit
• Guide de configuration
• Explication et images de la fonctionnalité 1
• Explication et images de la fonctionnalité 2
• Liens vers le support client

De même, une documentation logicielle pourrait suivre cette structure :

• Nom du logiciel
• Aperçu de l'objectif du logiciel
• Dépendances logicielles
• Guide d'installation
• Explication et images de la fonction 1
• Explication et images de la fonction 2
• Liens vers le support technique

Ces deux types de documentation sont étroitement liés et suivent une structure similaire. Cela signifie que les équipes produit et logiciel ont beaucoup à apprendre les unes des autres et ont un grand potentiel lorsqu'elles collaborent sur la documentation.

Les équipes de documentation produit et logicielle peuvent se compléter¶

Il existe des similitudes frappantes entre la documentation produit et logicielle. Cela soulève la question : les équipes produit et logiciel peuvent-elles travailler ensemble ?

Oui, elles le peuvent, et elles le devraient !

Les équipes logicielles comprennent le jargon technique et les technologies sous-jacentes. Les équipes produit comprennent ce que les utilisateurs voient, veulent et dont ils ont besoin ; l'expérience utilisateur. Les rédacteurs de documentation logicielle peuvent fournir des informations techniques détaillées, et les rédacteurs de documentation produit peuvent simplifier ces détails techniques pour les rendre accessibles à un public non technique.

Imaginez essayer d'expliquer quelque chose en termes simples, sans avoir la compréhension de haut niveau nécessaire pour formuler quelque chose qu'un profane comprendrait. C'est ce qui se passe quand la documentation produit est créée avant la documentation logicielle.

Qu'est-ce que la mécanique quantique ? Le chat de Schrödinger est probablement la première chose qui vous vient à l'esprit ! Mais quel rapport entre la mécanique quantique et les chats ? Pour l'utilisateur, ce n'est pas important. Pour un physicien, cela signifie tout.

Commencer par la documentation logicielle pour une meilleure documentation produit avec Docsie¶

En conclusion, utiliser la documentation logicielle comme modèle pour la documentation produit qui en découle présente de nombreux avantages. La documentation logicielle devrait servir de source unique de vérité pour le personnel informatique et les rédacteurs de documentation produit. Une fois rédigée, les rédacteurs de documentation produit auront la clarté et 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é.

En résumé, 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 formule Startup (gratuite pour toujours !) et offrez une documentation parfaite avec Docsie !