Que comprend exactement la «documentation»?

Lorsque nous parlons de «documentation» pour un produit logiciel, qu'est-ce que cela inclut et qu'est-ce que cela ne devrait pas inclure?

Par exemple, une question récente demandait si les commentaires sont considérés comme de la documentation?

Mais il existe de nombreux autres domaines pour lesquels il s'agit également d'une question valable, certains plus évidents que d'autres:

• Manuels (évidemment)
• Notes de version?
• Tutoriels
• commentaires
• Des autres?

Où est la ligne tracée. Par exemple, si «tutoriel» est de la documentation, est-ce de la documentation «tutoriel vidéo» ou s'agit-il d'autre chose?

Généralement, quelque chose dans un logiciel n'est pas «fait» tant qu'il n'est pas implémenté, testé et documenté. D'où cette question, quelles choses devrions-nous considérer dans le cadre de la documentation pour considérer quelque chose de «fait».

_{La question s'inspire des récents commentaires des clients lors de notre conférence indiquant que notre doc avait besoin de plus d '«échantillons», ce que nous n'avions pas été aussi bons à considérer que nous l'aurions dû.}

_{Public: développeurs de logiciels utilisant nos bases de données, nos langages de programmation et les outils associés (tels que les clients d'administration de ladite base de données)}

Le but de la documentation est de décrire et d'expliquer le produit logiciel, afin que vous puissiez définir la documentation comme l'ensemble des artefacts qui contribuent à cette description ou explication. Vous ne considéreriez probablement pas les actions connexes comme faisant partie de la documentation: par exemple, un cours de formation d'une semaine n'est pas de la documentation mais le matériel du cours l'est; un chat de tableau blanc de cinq minutes n'est pas de la documentation mais une image du tableau blanc l'est.

En gardant à l'esprit l'objectif (expliquer le logiciel), la documentation est terminée lorsque le client est satisfait de l'explication : tout comme le logiciel est terminé lorsque le client est satisfait du logiciel. Gardez à l'esprit que le client pour la documentation n'est pas toujours le même que le client payant pour le logiciel: le personnel de support, les testeurs, les vendeurs et autres auront tous besoin de comprendre ce que fait le logiciel et comment il fonctionne.

Cela permet de comprendre où se situe votre limite pour ce qui doit être inclus dans la documentation. Utiliser "lecteur" comme raccourci pratique, bien que nous acceptions que des vidéos ou du son puissent être inclus: tout ce qui aide le lecteur à obtenir les informations dont il a besoin sur le logiciel est une documentation qu'il peut utiliser, tout le reste ne l'est pas. Si votre client a besoin d'une présentation détaillée de tous ses cas d'utilisation, cela doit faire partie de la documentation. Vos développeurs ont probablement besoin de code source, d'informations sur votre référentiel de contrôle de version et d'instructions de construction: c'est de la documentation pour eux, mais comme décrit ci-dessus, cela ne fera pas partie de la documentation du client.

Je pense que vous avez retiré la mauvaise partie de votre conversation lors d'une conférence. Les méthodologies modernes de développement de logiciels préconisent que l'équipe de développement travaille en étroite collaboration avec ses clients (ou un propriétaire de produit qui agit en tant que proxy client). Pour tous les travaux livrés, la définition de «fait» est quelque chose qui est négocié entre l'équipe et son client et qui se fait de façon récurrente au fur et à mesure du développement du logiciel.

Le problème que vous avez rencontré est que vous aviez un décalage entre ce que vous supposiez que le client avait besoin et ce qu'il attendait de vous, donc à la fin vous avez eu la surprise "hé où sont tous les échantillons".

En ce qui concerne la documentation ... eh bien, c'est à peu près tout ce que vous avez énuméré et peut-être quelques autres choses que vous n'avez pas. Mais personne ne peut vous dire la quantité de documentation dont votre projet a besoin. Chaque projet est différent et c'est à votre équipe, à votre propriétaire de produit et à vos clients de déterminer le niveau et le type de documentation requis pour votre projet.

Quelques facteurs qui entreraient en jeu:

• Développez-vous des logiciels v1.0 et les passez-vous à d'autres projets ou s'agit-il d'un projet à long terme? Les commentaires / documents de conception deviennent beaucoup plus importants dans ce dernier cas. D'un autre côté, si votre client est un magasin de beignets maman-et-pop et que vous écrivez un site Web pour lui que vous ne verrez jamais ... eh bien, je suppose que la documentation du code est agréable mais pas si importante.
• Développez-vous un jeu mobile ou un logiciel qui contrôle le moniteur de fréquence cardiaque dans un hôpital. Devinez lequel aura la définition de «fait» qui a beaucoup plus de documentation?
• Vos clients sont-ils des utilisateurs finaux typiques ou d'autres développeurs? Avez-vous une API / SDK que vous exposez?
• Quel est le niveau d'expertise de vos clients? Cela affecte le choix du didacticiel vidéo par rapport au matériel écrit par rapport à une sorte d'application de didacticiel interactif
• Vos clients se soucient-ils de ce qui a changé d'une version à l'autre? Certains le font. La plupart n'en ont pas. Pour peu, c'est la loi (ou presque) de s'en soucier.

La documentation est une substance destinée à être lue sans la modifier.

Je pense que vous ne pouvez pas vous tromper avec la définition basée sur le but ... mais seulement si vous définissez correctement le but.

• ^{Définir correctement le but de la documentation n'est pas assez simple. Une distinction simple (naïve si vous le souhaitez) qui vient naturellement à l'esprit est que la documentation est tout ce qui est destiné à la lecture - tandis que, à titre de comparaison, le code est tout ce qui est destiné à l'exécution par ordinateur . Semble bien à la surface n'est-ce pas? mais cela se révèle vraiment très laid une fois que vous creusez plus profondément.
   
  Le fait est qu'un bon code prend en compte les problèmes de lisibilité, ainsi que l'exactitude de l'exécution - cela rend la distinction de "lisibilité" assez inutile dans la définition de la documentation.
   
  Les échantillons que vous avez mentionnés montrent ce qui ne va pas. Les clients attendent généralement ceux - ci soient clairement écrites etexécuter correctement. Compromettre la lisibilité ou l'exactitude peut apporter une cascade de plaintes des clients. La distinction naïve n'aide pas à déterminer si les exemples sont du code ou de la documentation.
   
  Utiliser la distinction naïve sera encore plus compliqué si vous imaginez travailler avec l' open source . Vous le téléchargez, le construisez et l'exécutez - vous ne le lisez pas, c'est juste le code non? Attendez, les choses ont mal tourné et vous obtenez le code pour lire ce qui se passe là-bas ... hé vous lisez ne pas exécuter - cette documentation est-elle maintenant? Et, enfin, vous trouvez un bogue dans la source et le corrigez - maintenant c'est vraiment le code, ce n'est pas quelque chose qui s'appelle normalement de la documentation, peu importe la façon dont vous le lisez attentivement pour faire ce correctif.}

Pour les « échantillons » que vous allez fournir, lecture sans distinction modify pourrait se révéler très important.

Regardez, si un échantillon échoue lorsqu'il est exécuté sans changement, dans l'environnement de référence documenté, c'est votre bogue - bogue dans votre documentation, celui que vous devez accepter et corriger, très bien.

Maintenant, s'il y a un problème avec un échantillon ou un environnement modifié, ce n'est plus de votre faute - je veux dire pas de bogue dans la documentation, car les documents ne sont pas destinés à être modifiés. Quelle que soit l'aide que vous fournissez aux utilisateurs dans un cas comme celui-ci, tomberait dans la catégorie de support, pas un correctif.

Tout ce qui répond à une question «comment puis-je ...» est de la documentation.

Pour les développeurs, cela signifie les spécifications des exigences ("comment savoir quoi écrire"), les documents de conception ("comment puis-je répondre à mes exigences"), les matrices de traçabilité ("comment puis-je savoir que ma conception répond à toutes mes exigences"), plans de test ("comment puis-je savoir que mon code fonctionne"), tests unitaires ("comment puis-je savoir que j'ai satisfait l'exigence X"), commentaires en ligne ("comment puis-je m'assurer que le prochain pauvre schlub comprend pourquoi je l'ai écrit ceci "), les instructions de déploiement (" comment emballer ce produit pour l'installation "), etc.

Pour les utilisateurs, cela signifie des manuels d'utilisation ("comment utiliser le logiciel"), des tutoriels ("comment utiliser cette fonctionnalité spécifique"), des notes de version ("comment savoir quels bugs ont été corrigés / de nouvelles fonctionnalités de bugs ont été ajouté "), etc.