Améliorez votre documentation avec JavaScript
Rendez la documentation de votre projet open source dynamique afin qu'elle plaise aux utilisateurs de tous niveaux d'expérience.
Les projets de logiciels open source comptent souvent un groupe d’utilisateurs très diversifié. Certains utilisateurs peuvent être très habiles à utiliser le système et avoir besoin de très peu de documentation. Pour ces utilisateurs expérimentés, la documentation peut se limiter à des rappels et des astuces, et peut inclure des informations plus techniques telles que des commandes à exécuter sur le shell. Mais d’autres utilisateurs peuvent être des débutants. Ces utilisateurs ont besoin de plus d’aide pour configurer le système et apprendre à l’utiliser.
Rédiger une documentation adaptée aux deux groupes d’utilisateurs peut s’avérer intimidant. La documentation du site Web doit trouver un équilibre entre « informations techniques détaillées » et « fournir plus d'aperçu et de conseils ». C’est un équilibre difficile à trouver. Si votre documentation ne peut pas répondre aux deux groupes d'utilisateurs, envisagez une troisième option : la documentation dynamique.
Découvrez comment ajouter un peu de JavaScript à une page Web afin que l'utilisateur puisse choisir d'afficher uniquement les informations qu'il souhaite voir.
Structurez votre contenu
Vous pouvez utiliser l'exemple où la documentation doit convenir aux utilisateurs experts et novices. Dans le cas le plus simple, vous pouvez utiliser un lecteur de musique inventé appelé AwesomeProject.
Vous pouvez rédiger un court document d'installation en HTML fournissant des instructions destinées aux experts et aux novices en utilisant la fonctionnalité de classe en HTML. Par exemple, vous pouvez définir un paragraphe destiné aux experts en utilisant :
<p class="expert reader"> Cela attribue à la fois la classe expert et la classe lecteur. Vous pouvez créer un ensemble parallèle d'instructions pour les novices en utilisant :
<p class="novice reader"> Le fichier HTML complet comprend à la fois des paragraphes destinés aux lecteurs novices et aux experts :
<!DOCTYPE html>
<html lang="en">
<head>
<title>How to install the software</title>
</head>
<body>
<h1>How to install the software</h1>
<p>Thanks for installing AwesomeProject! With AwesomeProject,
you can manage your music collection like a wizard.</p>
<p>But first, we need to install it:</p>
<p class="expert reader">You can install AwesomeProject from
source. Download the tar file, extract it, then run:
<code>./configure ; make ; make install</code></p>
<p class="novice reader">AwesomeProject is available in
most Linux distributions. Check your graphical package manager and search for AwesomeProject to install it.</p>
</body>
</html>Cet exemple de document HTML n'est associé à aucune feuille de style. Par conséquent, son affichage dans un navigateur Web affiche les deux paragraphes :
(Jim Hall, CC BY-SA 4.0)
Nous pouvons appliquer un style de base au document pour mettre en évidence n'importe quel élément auprès des classes de lecteurs, d'experts ou de novices. Pour faciliter la différenciation des différentes classes de texte, définissons la classe de lecteur sur une couleur de fond blanc cassé, la classe expert sur une couleur de texte rouge foncé et la classe novice sur une couleur de texte bleu foncé :
<!DOCTYPE html>
<html lang="en">
<head>
<title>How to install the software</title>
<style>
.reader {
background-color: ghostwhite;
}
.expert {
color: darkred;
}
.novice {
color: darkblue;
}
</style>
</head>
<body>
<h1>How to install the software</h1>Ces styles permettent aux deux sections de se démarquer lorsque vous affichez la page dans un navigateur Web. Les deux paragraphes contenant les instructions d'installation ont une couleur de fond blanc cassé car ils ont tous deux la classe Reader. Le premier paragraphe utilise du texte rouge foncé, tel que défini par la classe d'experts. Le deuxième paragraphe d'installation est en texte bleu foncé, provenant de la classe novice :
(Jim Hall, CC BY-SA 4.0)
Ajouter des contrôles JavaScript
Une fois ces classes appliquées, vous pouvez ajouter une courte fonction JavaScript qui affiche un seul des blocs de contenu. Une façon d'écrire cette fonction consiste à définir d'abord display:none sur tous les éléments avec la classe reader. Cela masque le contenu afin qu'il ne s'affiche pas sur la page. Ensuite, la fonction doit définir display:block sur chacun des éléments avec la classe que vous souhaitez afficher :
<script>
function readerview(audience) {
var list, item;
// hide all class="reader"
list = document.getElementsByClassName("reader");
for (item = 0; item < list.length; item++) {
list[item].style.display = "none";
}
// show all class=audience
list = document.getElementsByClassName(audience);
for (item = 0; item < list.length; item++) {
list[item].style.display = "block";
}
}
</script>Pour utiliser ce JavaScript dans le document HTML, vous pouvez attacher la fonction à un bouton. Puisque la fonction readerview prend une audience comme paramètre, vous pouvez appeler la fonction avec la classe d'audience que vous souhaitez visualiser, qu'elle soit novice ou experte :
<!DOCTYPE html>
<html lang="en">
<head>
<title>How to install the software</title>
<style>
.reader {
background-color: ghostwhite;
}
.expert {
color: darkred;
}
.novice {
color: darkblue;
}
</style>
</head>
<body>
<script>
function readerview(audience) {
var list, item;
// hide all class="reader"
list = document.getElementsByClassName("reader");
for (item = 0; item < list.length; item++) {
list[item].style.display = "none";
}
// show all class=audience
list = document.getElementsByClassName(audience);
for (item = 0; item < list.length; item++) {
list[item].style.display = "block";
}
}
</script>
<h1>How to install the software</h1>
<nav>
<button onclick="readerview('novice')">view novice text</button>
<button onclick="readerview('expert')">view expert text</button>
</nav>
<p>Thanks for installing AwesomeProject! With AwesomeProject,
you can manage your music collection like a wizard.</p>
<p>But first, we need to install it:</p>
<p class="expert reader">You can install AwesomeProject from
source. Download the tar file, extract it, then run
<code>./configure ; make ; make install</code></p>
<p class="novice reader">AwesomeProject is available in
most Linux distributions. Check your graphical package
manager and search for AwesomeProject to install it.</p>
</body>
</html>Une fois ces contrôles en place, la page Web permet désormais à l'utilisateur de sélectionner le texte qu'il souhaite voir :
(Jim Hall, CC BY-SA 4.0)
En cliquant sur l'un ou l'autre bouton, vous afficherez uniquement le texte que l'utilisateur souhaite lire. Par exemple, si vous cliquez sur le bouton « Afficher le texte du novice », vous ne verrez que le paragraphe bleu :
(Jim Hall, CC BY-SA 4.0)
Cliquer sur le bouton « afficher le texte expert » masque le texte novice et affiche uniquement le texte expert en rouge :
(Jim Hall, CC BY-SA 4.0)
Étendez cela à votre documentation
Si votre projet vous oblige à rédiger plusieurs documents pratiques pour différents publics, envisagez d'utiliser cette méthode pour publier une fois et lire deux fois. La rédaction d'un document unique pour tous vos utilisateurs permet à chacun de trouver et de partager facilement la documentation de votre projet. Et vous n’aurez pas besoin de maintenir une documentation parallèle qui varie uniquement dans les détails.