Un nouveau manuel écrit en AsciiDoc
Partie 1
Nous optimisons constamment Merlin Project pour le rendre plus facile à utiliser. Nous avons déjà commencé il y a quelque temps avec le dialogue de départ et le nettoyage de l'inspecteur.
Avec la version 8, l'aide dynamique est maintenant arrivée : Il suffit de cliquer sur le symbole ? pour obtenir un texte d'aide explicatif pour chaque objet que vous pointez avec la souris (ou avec votre doigt sur l'iPad). Vous pouvez même créer vos propres textes d'aide pour vos propres champs.
Mais malheureusement, notre manuel est un peu en retard. Mais ne vous inquiétez pas, il existe une documentation abondante et à jour, telle que :
- Un tutoriel,
- questions et réponses détaillées,
- beaucoup d'articles de soutien dans ce blog
- et bien sûr l'aide dynamique décrite au début.
Mais un manuel complet n'existe pas pour l'instant. Et c'est exactement ce que je voudrais changer maintenant.
Le projet
J'ai récemment commencé à réécrire le manuel et à créer cette référence. Bien sûr, j'ai mis en place un projet pour cela, mais malheureusement, il doit partager le temps disponible avec tous mes autres projets.
L'objectif
Outre l'objectif évident de créer une documentation à jour des fonctions de Merlin Project dans les (link: support/faq/usage/language text: langues les plus importantes, je me suis fixé quelques autres sous-objectifs ou sous-objectifs :
- Le manuel doit être disponible en HTML, PDF et eBook.
- L'impression à la demande doit être possible en tant qu'option.
- Le manuel devrait s'appliquer à tous nos produits, donc :
- Il sera proposé gratuitement sur notre site web, sur la librairie iTunes et sur d'autres sites.
Cependant, la date cible est totalement ouverte à toute planification, car j'ai une charge de travail différente d'une semaine à l'autre. Une date fixe comme objectif serait donc totalement irréaliste.
Les outils
Chez ProjectWizards, nous écrivons tous les textes au format ascii et les enregistrons dans notre git au plus tard en fin de journée.
Contrairement à la mode actuelle, nous n'écrivons pas en Markdown ou l'un de ses dérivés ou suppléments. Nous nous sommes déjà intéressés à AsciiDoc il y a très longtemps et depuis quelques années à Asciidoctor, la nouvelle implémentation de Dan Allen (via Twitter). Les raisons de cette décision sont principalement :
- Variables,
- la liaison d'autres fichiers,
- textes et formatages conditionnels,
- des tableaux, des diagrammes et de nombreux autres contenus,
- sortie de texte dans de nombreux formats différents,
- des tables des matières automatiques, ainsi que des glossaires, des index et des bibliographies
- et bien plus encore ...
Et avant que j'oublie, bien sûr, BBEdit est toujours défini comme éditeur #1 pour moi.
AsciiDoc vs Asciidoctor
En bref, vous donnez la source AsciiDoc à Asciidoctor et obtenez un résultat que vous pouvez publier. Donc :
- AsciiDoc est la langue
- Asciidoctor est le processeur
Comme Markdown, AsciiDoc a été conçu comme un langage pour être discret et concis, et pour rendre l'écriture plus facile, voire plus agréable. Mais AsciiDoc lui-même n'est pas un format de publication. Il s'agit plutôt d'un raccourci. C'est là qu'intervient un processeur AsciiDoc.
Un processeur AsciiDoc, tel qu'Asciidoctor, lit le texte source AsciiDoc et le convertit en formats publiables tels que HTML 5, eBook ou PDF. Bien entendu, l'ensemble du processus est complété par des outils de conception tels que les feuilles de style en cascade (CSS).
Travailler à voix haute (WOL)
Conformément à l'esprit de Working out Loud, j'essaierai de rendre compte régulièrement de ce travail. Je mettrai moins l'accent sur le nombre de mots ou de phrases que j'ai pu écrire pendant la semaine. Je suis beaucoup plus intéressé par la présentation des aides et des nouvelles perspectives d'Asciidoc et d'Asciidoctor.
Avec cette approche, je rends bien sûr hommage au travail inlassable de Dan Allen et je le soutiens. Au moins autant, c'est un vote pour Asciidoc dans la gestion de projet.
Vendredi prochain, nous commencerons à ce point.
