Bon après-midi
En tant que développeur du projet open-source
Embox , j'ai souvent entendu (trop souvent récemment) que le projet est intéressant, mais comme il n'y a pas de documentation, il ne peut pas être utilisé. Nous avons répondu qu'il y avait une sorte de documentation, que nous pouvons toujours répondre aux questions, que dans des cas extrêmes, vous pouvez essayer de le découvrir par vous-même, car le projet est ouvert, mais tout cela ne correspondait pas. J'ai dû faire face à ce sujet très désagréable pour les développeurs. Mais naturellement, l'article ne porte pas sur le fait que la documentation est «désagréable»! Et comment nous avons rendu le processus de développement de la documentation plus confortable. En effet, dans tout projet plus ou moins important, des problèmes liés à la documentation se posent nécessairement.
Pour ceux qui sont trop paresseux pour lire, je dirai tout de suite que nous sommes finalement arrivés au développement de la documentation au format markdown. Eh bien, pour ceux qui sont intéressés par les détails, les raisons du démarque et quels sont les avantages et les inconvénients de cette approche, je demande cat.
Je commencerai par justifier la pertinence du sujet. Non seulement Embox a des problèmes de documentation. Par exemple, Google a annoncé un analogue du programme Google Summer Of Code (GSOC) pour les rédacteurs techniques
Season of Docs . La société Kaspersky Lab organise des
conférences pour les rédacteurs techniques . Et la société Parallels publie des
articles sur le hub sur la façon d'écrire de la documentation . Tout cela indique que le sujet est important et peut-être privé à tort d’attention.
La série d'articles mentionnés ci-dessus comprend le contenu correct de la documentation, mais je veux me concentrer sur le processus de développement de la documentation, de la technologie, si vous le souhaitez. En effet, pour un projet open source, la marque de fabrique est l'ouverture en tant que propriété du processus de développement. Et nous voulions créer un processus qui satisferait aux exigences de notre projet.
Une brève digression dans l'histoire de nos processus de développement de la documentation.
Une fois le projet localisé sur
googlecode . Nous avions un wiki assez décent, beaucoup s'en souviennent même, demandent où le trouver et demandent de le transférer sur github, où se trouve le projet maintenant (ou dans un autre endroit accessible). Le wiki googlecode était vraiment pratique. Il était multilingue et avait, à mon avis, plus de fonctionnalités que le wiki sur github. Mais il se trouve que, avec le googlecode lui-même, il est tombé dans l'oubli. Le wiki actuel sur github remplit assez bien la fonction qui lui est assignée de fournir des informations opérationnelles sur le projet, mais il est assez difficile de créer une documentation complète sur cette plate-forme.
Bien sûr, pour tout projet open source, vous avez besoin à la fois d'une documentation en ligne (rapidement accessible) en ligne, dont le rôle est joué par le wiki, et d'une documentation complète disponible hors ligne, car il est beaucoup plus facile de comprendre l'essence et l'idéologie du projet. De plus, effectuer une recherche hors ligne sur un seul document, plutôt que sur des pages wiki disparates, est également beaucoup plus facile.
La meilleure option que je connaisse est probablement la
documentation ARM . C'est-à-dire, la documentation en ligne, où il y a une recherche dans toutes les sections, mais un document spécifique est disponible pour téléchargement au format pdf. Malheureusement, Embox n'a pas encore atteint le niveau d'ARM en termes de capacités. Par conséquent, nous avons dû faire la version hors ligne séparément. Pour cela, nous avons utilisé le service
Google Docs . Il est pratique car: il vous permet de télécharger des données dans différents formats, de collaborer et dispose d'un système de contrôle de version intégré. Nous avons transféré une partie des informations du wiki, défini la structure, car le but de développer la version hors ligne était de créer une documentation holistique, et avons commencé à développer plusieurs documents. Mais assez vite, nous avons rencontré des problèmes. Les informations étaient obsolètes, les données du wiki ne correspondaient pas aux données de la documentation hors ligne et, surtout, nous n'avons pas pu créer une documentation complète. Il y avait une structure, mais comme il n'était pas possible d'obtenir des commentaires décents des utilisateurs, il s'est avéré que seuls ses créateurs peuvent comprendre la documentation. Ce n'est certainement pas un problème de service, mais le fait, comme on dit, est évident. Nous avons dû chercher une approche différente de ce problème.
Ensuite, nous avons essayé de simplement transférer les données de l'ancien wiki vers le wiki github, mais même alors, nous avons rapidement rencontré des problèmes. Nous avons constaté qu'une partie des informations est obsolète, une partie n'a pas été ajoutée, une partie n'était pas claire sur la façon de les présenter sous une forme conviviale. Poursuivant la recherche d'une solution au problème, à un moment donné, nous avons même envisagé de développer de la documentation dans TeX en utilisant le référentiel git, mais nous nous sommes vite rendu compte que c'était déjà trop. Bien que cette idée ait eu un impact.
Nous avons décidé de formuler ce que nous voulons de la documentation, c'est-à-dire du processus de développement de la documentation, nous laissons le contenu en dehors des crochets:
- La documentation doit être conservée au format texte car elle était censée utiliser git comme système de contrôle de version
- La documentation doit avoir des versions en ligne (wiki) et hors ligne (documents séparés, par exemple, en pdf)
- La documentation en ligne et hors ligne devrait pouvoir se synchroniser facilement.
- La documentation doit être constituée de sections (chapitres) qui peuvent être développées ou étudiées séparément, mais à partir desquelles vous pouvez composer une documentation complète
Aucun des points ne contredit l'utilisation du markdown, et c'était intéressant car il est déjà utilisé sur le wiki. Vous pouvez bien sûr utiliser un format différent et le convertir en démarque. Mais après avoir compilé une autre liste d'exigences, cette fois à la possibilité d'ajouter différents types de contenu (images, texte, mise en forme), nous sommes arrivés à la conclusion que le démarque satisfaisait suffisamment tous nos besoins actuels. Et le tout premier google sur le sujet «démarque en pdf» a montré que les options pour convertir la démarque en d'autres formats existent et sont très populaires.
Il existe plusieurs options pour transformer le démarquage en pdf , mais
pandoc est de
loin le plus populaire. Cet utilitaire peut transformer n'importe quel format de texte en n'importe quel format de texte. De plus, il est en porte-à-faux. Par conséquent, il nous est non seulement familier, mais peut également être intégré dans des scripts pour créer de la documentation dans différents formats.
Nous avons décidé de l'utilitaire et avons commencé à réfléchir à la prochaine petite question que nous devions résoudre, à savoir comment créer un seul document, et pas beaucoup de fichiers pdf avec différents chapitres obtenus à partir de fichiers de démarque distincts. Le premier souhait était simplement de «sauvegarder les fichiers» (pour fusionner le texte de divers fichiers) dans l'ordre souhaité, mais cela s'est avéré beaucoup plus simple, pandoc lui-même est parfaitement capable de travailler avec la liste des fichiers. Cela nous a également permis de résoudre partiellement le problème que nous avons besoin de divers documents dans lesquels le contenu peut se croiser. Par exemple, nous générons trois documents et tous les trois contiennent une brève description. Nous listons simplement ce fichier dans la liste pandoc pour tous les documents.
Nous appliquons un principe similaire aux pages de garde contenant le titre du document, etc. Nous venons de créer des fichiers avec des en-têtes pour chaque document et les incluons comme premiers fichiers dans la liste source de pandoc.
Comme vous l'avez probablement deviné, cela (une liste de fichiers différents) résout le problème du multilinguisme, nous spécifions simplement les fichiers avec la langue souhaitée.
Parlons un peu plus du russe. Lors de la génération de pdf, pandoc utilise le latex comme backend pour le rendu, le correcteur orthographique, etc. Par défaut, le cyrillique n'est pas affiché et une erreur concernant un caractère inconnu s'affiche. Ceci est résolu très simplement, il suffit de spécifier «babel russian».
--- ... header-includes: - \usepackage[russian]{babel} ---
Il convient de noter qu’il est plus correct d’indiquer
--- ... header-includes: - \usepackage[russian, english]{babel} ---
Et utilisez les commandes latex dans le texte
\selectlanguage{russian} \foreignlanguage{english}{ English text }
Ou
\begin{otherlanguage}{english} Text in english \end{otherlanguage}
Mais comme nous voulions garder une démarque «propre» pour un éventuel transfert sur le wiki, et qu'il s'est avéré que la directive babel était suffisante pour nous, nous avons décidé de ne pas la compliquer et de la laisser telle quelle.
Bien sûr, nous voulions avoir des documents non formatés, mais au moins avoir l'air uniformes. Et ici, le latex nous a de nouveau aidés. Le fait est que, puisque pandoc utilise du latex, vous pouvez lui spécifier des modèles de latex. Cela se fait simplement avec l'option --template
pandoc --template=embox_pandoc.latex ...
Après avoir compilé un modèle et l'avoir spécifié lors de la génération de tous les documents, vous obtenez des documents dans un style plus ou moins uniforme. «Plus ou moins» - car il y a plusieurs problèmes que nous n'avons pas pu résoudre. Par exemple, la formation d'un seul bloc de code. Dans le démarquage, il est possible de spécifier un seul bloc de code afin qu'il ne soit pas formaté et que la coloration syntaxique soit éventuellement activée. Mais nous avons réussi à ne faire que des blocs d'une seule ligne. Cela s'est avéré après avoir regardé le code latex généré.
Autrement dit, il y avait des cas où le même bloc était placé sur différents documents un peu différemment.
Un autre point lié à l'alphabet cyrillique, c'est l'utilisation de la langue russe. Comme mentionné ci-dessus, pour utiliser la langue russe, il s'est avéré suffisant de spécifier le babel russe dans l'en-tête. Mais nous étions confrontés à certaines bizarreries, par exemple, il n'y avait pas de surbrillance en gras et d'autres bizarreries de formatage. Au départ, nous avons péché sur le fait que le russe est spécifié en majuscules et non dans un modèle. Ils ont commencé à étudier le problème. Il s'est avéré que dans le bon sens, vous devez non seulement utiliser
\usepackage[russian, english]{babel}
mais aussi
définir des polices \usepackage[T1,T2A]{fontenc} \usepackage[utf8]{inputenc}
Mais même après cela, il n'a pas été possible de rectifier la situation. Il s'est avéré que tous les jeux de polices ne contiennent pas toutes les options de rendu, en particulier les nôtres ne contiennent pas de gras, italique et ainsi de suite d'autres formats. Puisqu'il n'y avait pas de solution simple au problème, nous avons pensé et reporté le problème jusqu'à des temps meilleurs. Eh bien, puisque nous voulions utiliser une démarque claire (c'est-à-dire sans spécifier de commandes latex), nous avons créé un modèle commun pour les deux langues, et l'indication sur la langue russe a été placée dans l'en-tête.
Je dirai juste quelques mots sur l'interface de l'application elle-même. Puisque, comme je l'ai dit, les applications de console nous sont personnellement très familières et sont facilement regroupées en scripts. En fait, l'interface est simple, bien sûr, vous pouvez définir de nombreuses options, mais pour nos besoins, il suffit de spécifier un modèle, une liste de fichiers d'entrée et un fichier de sortie.
pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file>
Sur Internet, vous pouvez constater que pour générer un pdf (ou un autre format de sortie), vous avez besoin d'un type de processeur utilisant l'option --pdf-engine = xelatex, mais par défaut, il est utilisé si le fichier de sortie a l'extension pdf. Par conséquent, nous n'en avions pas besoin non plus.
Nous avons emballé les scripts pour assembler la documentation dans un Makefile, afin qu'elle devienne assez familière. Et maintenant, pour obtenir la documentation, vous pouvez définir l'environnement nécessaire, appelez simplement
make [en][ru]
En conclusion, quelques mots sur le système de contrôle de version. Le principe n'est pas de compliquer (rester simple) on a essayé de tout adhérer. Et puisque la solution la plus simple était d'utiliser un référentiel séparé sur github,
nous l'avons fait . Nous espérons que l'utilisation de github améliorera les commentaires des utilisateurs. Après tout, comme vous le savez sur github, il y a des problèmes dans lesquels vous pouvez discuter des lacunes et proposer vos idées et vos directions.
Ce processus a été lancé récemment, à la demande de nombreux travailleurs! Nous avons réussi à créer les versions
anglaise et
russe du «démarrage rapide», ainsi que la
première version du manuel d'utilisation russe . Le processus lui-même nous a semblé plus pratique, c'est pourquoi nous le partageons avec le public.