Il y a quelques mois, j'ai terminé l'une des étapes de ma carrière professionnelle en tant que Shiva à bras multiples dans une startup sur le développement d'un système de gestion de laboratoire de tests non destructifs. Je vais vous dire comment j'ai pu documenter une partie du développement lié à la connexion et à la génération de documents en volume suffisant pour une utilisation silencieuse du système créé pendant deux ans.
Je vais essayer de donner au lecteur du matériel utile autant que possible, et en même temps observer les intérêts du projet et ne pas divulguer les nuances de mise en œuvre et d'utilisation interne.
Étant donné:
- cool équipe de développement et bien sûr le chef de projet. Au moment du démarrage du projet, j'ai travaillé comme directeur artistique dans l'un des studios de Tomsk, puis je me suis retrouvé dans l'équipe startup
- start-up avec des dates en béton armé pour un événement spécifique - démarrage de l'accélération dans le FRII
- ensemble initial de modèles à partir de 15+ documents de différentes tailles de 1 page à 100+ pages dans un document avec différentes conditions de connexion
- projet tiers devant être intégré à une future solution
- designer (analyste, designer, designer, directeur artistique, propriétaire de produit, chef de produit tous réunis)
Défi:
- lancer un projet à temps
- ne mourez pas de l'équipe six mois plus tard dans le chaos lors de la connexion de nouvelles fonctionnalités et encore plus de documentation dans le système (en cas de réussite de l'accélération)
- avec le nombre minimum de lettres et les efforts déployés pour obtenir une documentation appropriée
- aliénation de la documentation à toute équipe / tout employé hors contexte
Je dois dire tout de suite que les modèles de documents suivants ont été réalisés sans aucune méthodologie, j'étais uniquement guidé par les spécificités du projet, le bon sens et un délai très court.
Analyse et préparation
J'espère que vous commencerez toute tâche non triviale en analysant le matériel, dans mon cas, le matériel était des modèles de documents et un projet existant avec lequel l'intégration était nécessaire. Mais nous ne parlons alors que de documents. J'avais besoin de déterminer la fréquence d'utilisation du même type de données dans le même document et entre les documents. Il était nécessaire de comprendre si un système est nécessaire en ce moment ou si vous pouvez le faire rapidement sur le genou en premier, puis gérer le résultat. À cette époque, il a été décidé que le système était nécessaire, car presque toutes les données, dans un volume ou un autre, étaient répétées dans un document et dans l'ensemble du paquet de documents - et c'est un signe certain de confusion déjà sur le deuxième ou le troisième document lors de la connexion.
L'étape suivante consiste à comprendre l'état de propreté du balisage des documents. Je vais vous expliquer. Le fait est que j'ai reçu des modèles de documents déjà remplis du méthodologiste - qui, quand et comment ces documents je ne savais pas, même si je savais que cela aurait donné peu. Le document .docx à l'intérieur est quelque chose comme xml pour le texte et certains éléments peuvent ne pas être visibles visuellement dans un document ouvert, mais être présents dans le balisage du document. On ne sait pas comment le générateur de documents et les divers logiciels pour visualiser le document réagiront à ces éléments de balisage. Le pari principal était sur Microsoft Word, mais il existe OpenOffice, LibreOffice et tous peuvent donner des résultats différents. Par conséquent, tous les modèles ont d'abord suivi la procédure de nettoyage des styles - une réinitialisation complète de toute conception et une nouvelle conception des styles de document, quelque part avec l'ajustement de la structure du document. Et même après cette procédure, nous avons collecté des problèmes dans le contenu des documents après la génération. À l'avenir, je suis arrivé à la conclusion que si le document est petit, il est préférable de le trier à partir de zéro, et de ne pas utiliser le modèle fourni par le méthodologiste, cela économise du temps sur des documents jusqu'à 5 pages. Personne ne veut alors chercher la raison pour laquelle quelque chose s'est passé, le processus de débogage de ces cas est extrêmement fastidieux pour l'équipe. Au même stade, si vous avez un paquet de documents, vous arrivez à un langage visuel uniforme.
Et puisque nous avons effectué un rite de nettoyage de documents, l'œuf de Pâques dans la méta-information s'est suggéré, parce que les gens aiment partager de bons documents
Après tous les travaux liés à la préparation des documents, j'ai procédé au balisage des documents pour la génération automatique.
Balisage des documents
À ce stade, demandez aux développeurs le format variable qui prend en charge le générateur de documents sélectionné par votre équipe afin que vous n'ayez pas à le refaire plus tard. J'ai dû le refaire, mais cela était dû au remplacement du générateur. Le nouveau générateur ne pouvait pas fonctionner avec les variables du format précédent, mais les capacités du nouveau générateur se sont avérées plus importantes pour nous et nous avons décidé de le remplacer.
Vérifiez la suffisance des informations dans le système, déterminez la quantité de données insuffisante pour le document. Quand ces données sont-elles censées apparaître sur le système? S'il n'y a pas suffisamment de données pour l'autosuffisance du document, il est préférable de le reporter. Qu'est-ce que l'autosuffisance des documents? Dans mon cas, il y avait un document que nous avons rempli en 3 étapes, mais il était auto-suffisant immédiatement pour un scénario spécifique, mais ne couvrait pas le reste des scénarios, nous avons donc décidé de déployer le document pour la vente, en laissant des cellules vides à remplir par l'utilisateur pour les scénarios non découverts, et par la suite terminé le document avec l'apparence de la fonctionnalité nécessaire.
Documentation sur les variables et les interfaces
Au début de la note, j'ai écrit que nous étions strictement limités à un événement spécifique. En plus de cela, j'avais déjà prévu des vacances. Lorsque je n'étais pas disponible, mais que j'avais un besoin urgent d'ajouter une variable système (non disponible dans l'interface utilisateur final), les développeurs ont ajouté la ligne avec la variable eux-mêmes, puis j'ai ajouté les conditions manquantes. À cet égard, la spécification des variables ne prétend pas être correcte et idéale, mais c'est tout à fait un document de travail, qui s'est ensuite développé et évolué. L'onglet principal du document n'a pas changé structurellement depuis le début et au moment de mon départ du projet.
Modèle «
Spécifications pour ces domaines », que vous pouvez prendre et utiliser dans votre travail. Dans le document, j'ai laissé une partie des données pour un exemple. Ce modèle peut convenir à la documentation de l'interface pour contrôler la qualité du développement. Par exemple, un propriétaire de produit sait quel résultat minimum il obtiendra, un développeur comprend clairement quel minimum doit être fait à partir de la description de la tâche + spécification de ces champs, et si quelque chose manque, il en parlera, l'ingénieur de test voit clairement des cas évidents. Au final, tout est dans le noir.
Au début, le document prendra un nombre important d'heures, mais ensuite il vous fera économiser beaucoup de temps, et la mise à jour prendra parfois littéralement quelques minutes.
Contenu:
- La page est un guide pour une personne en dehors du contexte du projet, où chercher. Utile pour un nouveau membre dans une équipe ou pour externaliser un projet.
- Nom du champ
- Type de champ
- Champ obligatoire dans les projets (je vous rappelle que nous avions une base de données d'un autre projet) - un marqueur pour synchroniser l'exigence de liaison entre le document et l'interface. Si les informations du document sont contraignantes et que le système ne peut pas les recevoir d'une autre manière, il sera nécessaire de rendre ce champ obligatoire dans l'interface
- Masque de champ - le format d'enregistrement des informations est clairement défini dans la documentation réglementaire.
- Valeur par défaut
- Le nombre maximum de caractères dans le champ
- Évolutivité du champ (dépend de la résolution) - description du comportement d'un élément d'interface en fonction de la résolution
- Exigence de données - quelle interaction est autorisée avec l'élément d'interface et ce qui peut entrer
- Échantillon réussi
- Espace réservé - info-bulle pour l'utilisateur à l'intérieur de l'élément d'interface
- Personnalisation du champ - éléments d'interface non standard ou tâches terminées
- Informations supplémentaires à côté du champ - lorsque l'espace réservé ne peut être supprimé en raison de la quantité de texte, nous utilisons une info-bulle ou une poignée
- Type de validation
- Message de validation - conditions du système et réponse
- Variable dans les modèles de document - ce qui sera inséré dans le modèle de document
- Lien vers la page - n'a pas utilisé en conséquence
- Emplacement du champ dans l'interface - n'a pas été utilisé en conséquence
Documentation de connexion de documents
Pour recevoir le document par l'utilisateur final, il ne suffit pas de le modifier et de le baliser; le document doit encore être connecté correctement. Il est particulièrement important si vous avez le même modèle, selon les conditions, change son contenu. Pour cela, j'ai utilisé un document séparé.
Template "
Document Connection ", j'espère qu'il sera utile à quelqu'un.
Contenu:
- État - indique l'état actuel du document dans le système. Nous avons connecté un document en 3 étapes, le statut du document était «Finaliser»
- Document - le nom du document au sein de l'équipe, de la base de connaissances et de notre système de documentation et de définition des tâches
- Tapez
- Le format du document est lorsque le même document peut être dans différents modèles en fonction de la documentation réglementaire et technique à laquelle ce document correspond
- Formation - un document peut être juste un modèle dans lequel des variables sont simplement substituées ou à partir d'un modèle de 3 pages, vous pouvez obtenir plus de 100 pages de documents - documents dynamiques
- La présence dans le package est une caractéristique du système, vous pouvez obtenir un package de documents ou télécharger des documents séparément
- Condition de disponibilité - la présence d'un document spécifique dans le colis
- La fonctionnalité de connexion est la partie du document qui n'est pas dans le modèle et qui est réglementée par le code.
- Lien vers le fichier à connecter
- Téléchargez séparément
- Le nom du fichier à télécharger - un document dans le système peut être appelé comme vous le souhaitez, mais l'utilisateur final doit voir un nom spécifique lors du téléchargement
Total
En conséquence, j'ai rempli 362 lignes dans les deux documents. Un volume impressionnant? Mais en réalité, il s'agit de plus de 30 modèles de documents et un total de 40 à 60 heures de travail d'une personne a été consacré en deux ans (1-1,5 semaines), à l'exclusion de la modification des modèles eux-mêmes et du libellé des tâches de connexion.
Le projet a passé avec succès l'accélération de l'IIDF et a pris la forme de sa propre équipe de développement. Grâce à la documentation existante, les nouveaux membres de l'équipe n'ont pas eu à se plonger longtemps dans ce qui a été fait avant eux en matière de génération de documents. Tous les membres de l'équipe avaient accès à tout moment à l'état actuel des documents connectés.
Les principales étapes de la documentation du processus de génération de documents:
- Analyse du contenu des documents
- Hygiène des documents
- Correction des variables en parallèle avec le balisage du document
- Corrigez les nuances de la connexion des modèles de documents.
Merci d'être arrivé au bout.