Bien que la deuxième réunion de Write the Docs Moscou ait eu lieu il y a un mois, il n'est jamais trop tard pour publier un rapport et de courts résumés de rapports. Nous avons réussi à discuter, enfin, pratiquement de tout: de la documentation d'une API RESTful aux trajectoires professionnelles d'un rédacteur technique.
Mitap, en passant, a réuni non seulement le «ghetto technique», mais aussi un large éventail d'autres spécialistes qui travaillent d'une manière ou d'une autre sur la documentation du projet: chefs d'équipe, analystes, testeurs et même un directeur technique.
Notre
rencontre a eu lieu le 14 octobre , dimanche (il est entré en tête des questions les plus populaires à son sujet, "Pourquoi dimanche?") Au bureau d'IPONWEB. Les rassemblements Write the Docs ont lieu dans le monde entier de Bangalore à San Francisco, de Londres à Séoul, la branche russe de la communauté ne fait que gagner en activité, mais il existe déjà des branches à Moscou, Saint-Pétersbourg et Novossibirsk.
Anton Telin, Pourquoi et comment nous faisons des instructions vidéoVidéoDiapositivesAnton gère le département de documentation technique de VLSI, qui crée un système de gestion électronique des documents. Pourquoi une vidéo? Les gens ne veulent pas lire les instructions, ils veulent résoudre un problème. Les gens veulent qu'on leur explique clairement et clairement.
La vidéo est un moyen pratique de présenter une grande quantité d'informations, de mettre en œuvre un script en dynamique, une séquence d'actions. Vous pouvez également accentuer l'attention de l'utilisateur avec de la musique ou un doublage.
Si le produit est complexe et ne dispose pas d'une interface bien pensée, alors sans la partie visuelle, il est difficile de transmettre son essence à l'utilisateur. Le plus est qu'il réduit le coût du support technique.
Inconvénients - ne convient pas à tous les formats de publication, il est difficile de l'intégrer au format doc et pdf. Il est difficile de le rechercher. Les vidéos de haute qualité sont plus chères.
Un autre problème urgent est la complexité de la mise à jour, mais la campagne d'Anton a résolu ce problème. Ils ont refusé d'enregistrer des captures d'écran (captures d'écran) en faveur de captures d'écran de haute qualité.
L'entreprise utilise deux formats vidéo:
1. L'instruction vidéo est une séquence d'actions, en détail et par étapes. Durée ~ 2 minutes. 1 instruction est 1 problème. Il ne parle pas de toutes les fenêtres, choucas, boutons. Ajout de doublage, musique de fond, explications de texte, légendes.
2. Vidéo explicative. C'est quelque chose à la jonction de l'instruction et de la présentation du produit. Une vue générale sans détails techniques résout plusieurs problèmes ou scénarios. Cette vidéo peut inclure des personnes et des animations. Durée 2-3 minutes.
Outils: Adobe Premiere et Adobe After Effect pour l'édition, Adobe Audition pour le son, Photoshop et Snagit pour l'édition des images. Le projet est assemblé à partir d'une variété de captures d'écran, qui ne sont pas pertinentes ou erronées, il est donc facile à remplacer. Ensuite, dessin du mouvement de la souris, animation, son.
Ils ont décidé d'utiliser des annonceurs non professionnels pour le doublage, car ils semblaient trop formels, ils utilisent donc la voix d'un employé de la société, Ilya, qui chante dans un groupe de metalcore. Après un bloc d'informations, une pause de 2 secondes pour la compréhension est forcément donnée.
Les vidéos sont publiées à la fois sur votre propre hébergement et sur Youtube. L'inconvénient est de le bloquer par de nombreuses entreprises pour des raisons de sécurité.
Bien sûr, VLSI collecte toutes les statistiques disponibles: durée moyenne de visionnage, likes, appels au support technique qui ont été fermés à l'aide du lien vidéo.
Nikolay Volynkin, rédacteur technique version 2.0.1VidéoDiapositivesCeci est une répétition, ou mieux dit, un ajout au rapport de la conférence SECR. Nikolai a regardé les rédacteurs techniques pendant longtemps et a remarqué qu'ils ne savent pas toujours comment justifier et mesurer leurs avantages, et les dirigeants qui leur confient également des tâches.
Il existe certaines tâches connexes que les rédacteurs techniques pourraient résoudre. Nikolay a indiqué quelles trajectoires de carrière et quels ensembles de compétences ont des descriptions techniques, comment vendre vos nouvelles tâches à l'entreprise.
5 rôles qu'un rédacteur technique peut jouer:
1.
Docops - devops pour la documentation, rédacteur / programmeur, il peut automatiser la génération, la vérification, le téléchargement de la documentation, forme l'équipe à travailler avec elle et reconstruit tous les processus qui l'entourent.
Les avantages sont une réduction du travail manuel, des économies de ressources et des vitesses de livraison des fonctionnalités plus élevées.
2.
UX écrivain - un spécialiste de l'écriture de textes dans les interfaces.
Avantages - les concepteurs, les poèmes, les analystes ou les développeurs front-end ne comprennent pas toujours comment écrire correctement, comment transmettre des fonctions, des boutons, des transitions à l'utilisateur. Les textes sont écrits selon le principe de la première personne qui s'est levée et des chaussons. Commodité de l'interface, réduisant le temps de support technique.
3.
Évangéliste technique , il parle de technologie, interagit avec la communauté, la façonne.
Avantages - confiance et fidélité accrues à l'entreprise, au produit, simplification du recrutement, marque RH.
4.
Knowledge Manager - explore comment une entreprise produit, stocke et transfère ses connaissances. Établit ces processus afin que les connaissances ne fuient pas.
Avantages - facteur de bus réduit, vitesse d'adaptation des employés, débutants et en transition, réutilisation des connaissances, réduction des risques.
5.
Propriétaire de la documentation - PM et analyste de la documentation. Il construit l'ensemble du système de communication et d'interaction utilisateur dans la documentation.
L'avantage réside à nouveau dans la réduction des coûts de support.
Au cours de la discussion, nous avons rappelé un rôle aussi intégré en tant que gestionnaire de contenu, qui n'était pas mentionné dans le rapport.
Konstantin Valeev, FoliantVidéoDiapositivesConstantine de Restrim a parlé de l'outil
Foliant - l'implémentation d'un workflow docops basé sur le langage Markdown. Il y a un an, dans le cadre du
mini-Hyperbaton de Yandex, Konstantin parlait déjà de Foliant, et beaucoup de choses ont changé depuis.
La documentation est écrite dans des fichiers MD, et se trouvant à différents endroits, l'outil prend en charge l'intégration continue, l'assemblage automatique et il vous permet également d'étendre MD à votre guise.
Exigences: vous devez donner docx pour les clients et PDF avec une bonne typographie, avoir des sources lisibles par l'homme (pas XML).
Sous le capot, un convertisseur Pandoc universel est utilisé, Python, les scripts bash sont enroulés sur le dessus. Mais au fil du temps, le nombre de scripts a augmenté, ils ont donc été réécrits en une seule application monolithique.
À partir du monolithe, ils ont ensuite réalisé une structure modulaire avec le noyau contrôlant l'assemblage, des préprocesseurs qui convertissent le MD pour le travail des assembleurs et les assembleurs eux-mêmes.
Foliant est essentiellement la colle entre de bons outils (mkdoc, pandoc, ardoise, latex). Maintenant, ils essaient d'enseigner comment consommer des sources de documentation de différents formats.
Dans le dossier du projet, il y a une configuration avec la structure du document final, les styles et les fichiers MD réels, puis les préprocesseurs prennent les fichiers MD source et leur appliquent un traitement pour créer le MD souhaité dans le style de all.md (md dans le style de foliant), puis les collecteurs des documents finaux ( pandoc, mkdoc) en font des cibles (documents). Après l'assemblage MD, des linters sont exécutés pour vérifier la syntaxe. Des notifications de build sur les builds ou les bugs sont également envoyées.
Tout cela peut être collecté dans Docker, afin que tous les colis soient livrés d'une seule manière, et non chacun séparément.
Foliant prend en charge les fonctions avancées d'inclusion, peut extraire des morceaux de code de Gitlab / Github et des images avec des mises en page de Simpli, peut dessiner des diagrammes, remplacer des paramètres dans le texte, des instructions conditionnelles.
Nikita Samokhvalov, Documentation complète sur l'API RESTfulVidéoDiapositivesNikita Samokhvalov, directeur technique de Notamed, a expliqué comment ils avaient configuré la génération de documentation API basée sur Open API 3.0.
Comme tout le monde, ils ont commencé avec Google Docs, mais il n'a ni version ni capacité de créer des branches. Ensuite, ils ont juste commencé à écrire des fichiers MD dans le référentiel, le problème de version et de création de branches a été résolu, mais tout était lent. Puis est venu l'auto-génération.
La documentation avait les exigences suivantes: héritage et réutilisation de pièces de documentation, la capacité de fournir un lien vers des descriptions de paramètres et de méthodes, des informations sur la différenciation des droits d'accès, la documentation sous forme de code (déploiements et modifications synchrones). De plus, la documentation n'est pas publiée publiquement, uniquement pour votre équipe et vos équipes de développement diplômé.
Nous avons choisi la spécification OpenAPI 3.0. Pourquoi? Il est le plus frais, il prend en charge plus de fonctionnalités, bien qu'il existe encore un petit écosystème et une expertise autour de lui.
Ils ont pris l'outil
shins (montre les fichiers MD dans une belle page de destination avec des exemples de requêtes, une description des méthodes, des paramètres), des
widdershins (
convertisseur yaml / json en MD), ils ont également écrit leur propre package
specker (installe toutes les dépendances nécessaires, fonctionne via npm, vérifie également l'exactitude de la structure d'allocation des fichiers).
La configuration de l'environnement et l'assemblage de la documentation se font sur une seule ligne dans la console. Les fichiers qui doivent être réutilisés dans chaque projet, par exemple une description d'autorisation, tombent dans le dossier dependencies /.
Nikita a également parlé de la façon dont ils travaillent avec les succursales dans une équipe distribuée, lorsque la tâche consiste à mettre à jour la documentation et, bien sûr, des pièges et des difficultés qui ont accompagné la mise en œuvre d'OpenAPI 3.0.
Svetlana Novikova, Gestion des connaissances à l'aide de la matrice des compétencesVidéoDiapositivesSvetlana (au fait, c'est moi) a expliqué comment, au sein de l'entreprise, ils ont organisé un redémarrage de l'instrument de bout en bout à partir de la sphère de gestion du personnel en tant que matrice de compétences, à quoi sert la gestion des connaissances de cette manière, comment l'instrument aide-t-il à réduire le facteur bus, il est préférable d'embarquer des nouveaux arrivants, même de trouver des pièces code de refactoring.
Danila Medvedev, NeuroCodeVidéoDanila a parlé d'un outil qui est compréhensible par tout le monde, et peut-être en avance sur notre temps, pour modéliser et stocker des connaissances appelé NeuroCode.
Cet outil est utile à toute personne impliquée dans la conception de systèmes informatiques. En particulier, Danila suggère d'abandonner les systèmes basés sur des documents. Tout système est considéré comme un réseau, selon les nœuds dont certaines informations sont transmises. Tous les éléments du système obéissent à ce principe - mises à jour push, transfert de documents, transfert de feedback. Le NeuroCode a pour objectif «de réduire les coûts improductifs de support des processus et de renforcer l'intelligence collective de l'organisation».
Le projet NeuroCode est né de la résolution du problème - comment créer un bon référentiel d'informations pour une équipe ou pour vous-même, comment créer un modèle d'informations. Le prototype du système est fait et fonctionne, il est maintenant testé avec l'aide d'ingénieurs système et d'architectes commerciaux. Le système a une interface évolutive et est basé sur une structure de données fractale. Il est également basé sur les idées de Douglas Engelbart (c'est l'un des premiers chercheurs sur l'interface homme-machine, auteur des concepts de GUI, d'hypertexte, etc.) des années 1960 sur les systèmes ouverts hyper-documentaires (OHS), lorsque le système n'est pas basé sur des documents, mais un seul c'est-à-dire qu'il met en œuvre tous les processus de l'activité humaine.
PS En général, mieux vaut regarder la vidéo.
La prochaine réunion,
Write the Docs Moscow, aura lieu le 7 décembre au bureau de Positive Technologies et se tiendra sous le format de Positive Authoring Tools Battle.
