Comment rédiger une documentation technique accessible

Article original : How to Write Accessible Technical Documentation – Best Practices with Examples

Lorsque vous rédigez une documentation technique pour un projet ou un outil sur lequel vous travaillez, vous voudrez qu'elle soit accessible. Cela signifie qu'elle sera adaptée et utilisable par le public mondial diversifié sur le web.

L'accessibilité web vise à rendre possible pour quiconque d'accéder au contenu web. Il existe des bonnes pratiques d'accessibilité communes pour les designers, les développeurs et les rédacteurs. Cet article couvrira certaines bonnes pratiques pour créer du contenu technique.

Qu'est-ce que l'accessibilité web ?

L'accessibilité web est la pratique qui consiste à rendre possible pour quiconque de consulter ou de créer du contenu sur le web, quels que soient les défis de santé, économiques, géographiques ou linguistiques qu'ils peuvent rencontrer.

Pourquoi l'accessibilité web est-elle importante ?

Il est important d'appliquer les bonnes pratiques d'accessibilité web dans vos projets pour plusieurs raisons.

Tout d'abord, cela vous aidera à atteindre un public plus large. Lorsqu'une personne ayant des capacités différentes tombe sur des données sur le web – disons sur votre site web – elle voudra en savoir plus ou utiliser les données. Mais si elle n'est pas en mesure d'y accéder, elle ne sera pas heureuse ou n'aura pas une bonne expérience.

Imaginez combien de personnes ne peuvent pas utiliser le web parce qu'elles ne sont pas prises en compte lorsque les développeurs et les designers prennent des décisions sur la manière dont le produit, le site web ou l'outil sera construit.

Une autre chose importante concernant l'accessibilité est qu'elle améliore la qualité de votre marque. Faire savoir aux gens que vous êtes une personne ou une entreprise axée sur l'accessibilité en l'implémentant dans votre travail montre que vous voulez que vos informations soient disponibles pour tous. Cela montre également votre polyvalence dans votre métier et votre capacité à vous améliorer et à vous adapter aux temps et aux tendances changeants.

De plus, en tant qu'individu, l'application des bonnes pratiques d'accessibilité vous bénéficie également. Il existe des opportunités d'emploi possibles pour les développeurs et les designers ayant de grandes compétences en accessibilité.

Les bonnes pratiques d'accessibilité signifient également de bonnes pratiques SEO, ce qui peut entraîner une plus grande visibilité pour votre travail.

Enfin, l'accessibilité est imposée par la loi dans certains pays du monde, et des stratégies d'accessibilité web sont mises en œuvre par certains pays. Il pourrait y avoir des conséquences légales si vous négligez l'accessibilité sur vos sites web et applications.

Comment rédiger une documentation technique accessible

Les ingénieurs logiciels jouent un rôle clé dans la rendre le web accessible. Mais lorsqu'il s'agit de rédiger de la documentation, les rédacteurs techniques ont également un rôle à jouer dans l'amélioration de l'accessibilité web.

Les rédacteurs techniques aident à écrire divers types de contenu, comme des guides utilisateur, des tutoriels, des références API, de la documentation de code, et ainsi de suite.

Maintenant, examinons certaines des bonnes pratiques pour implémenter l'accessibilité web dans la rédaction technique. Ces stratégies aideront à améliorer votre documentation et à la rendre plus conviviale et accessible à tous.

Utilisez des titres et des paragraphes clairs

Lorsque vous rédigez du contenu, vous devez veiller à utiliser des titres – ainsi que la hiérarchie des titres appropriée (H1 pour le titre de la page/article, H2 pour les titres principaux, H3 pour les sous-titres, et ainsi de suite).

De plus, assurez-vous de diviser votre contenu en paragraphes pour qu'il soit plus facile à lire et à comprendre.

Lorsque vous introduisez un nouveau sujet, utilisez un titre pour le mettre en avant. Lorsque vous parlez de sujets plus petits dans cette section, utilisez des sous-titres pour alerter le lecteur.

Les titres sont également importants pour aider les lecteurs d'écran à comprendre le contenu d'une page et comment naviguer à travers eux. Utilisez donc des titres pour guider les lecteurs à travers le texte de manière logique.

Vous désignez les titres en markdown avec des dièses. Voici un exemple de titres dans l'ordre hiérarchique.

# Utilisez H1 pour le titre de la page

## Utilisez H2 pour les titres principaux
Ce titre est un titre principal pour le contenu de la section principale.

### Utilisez H3 pour les sous-titres
Ce titre est un sous-titre qui approfondit l'un des points de la section principale.

Rendez votre contenu clair et concis

Dans l'ensemble, essayez de garder vos phrases assez courtes dans vos documents. Cela les rend plus faciles à lire et à comprendre (pour tout le monde). Vous pouvez également utiliser des images ou des vidéos pour fournir plus de détails si nécessaire.

Assurez-vous de donner les significations complètes de tous les acronymes que vous utilisez pour la première fois. De plus, utilisez toujours des phrases simples et essayez de ne pas utiliser de mots ambigus.

Voici un exemple de phrase trop complexe, longue avec un vocabulaire difficile :

Le web3 fonctionnant sur la structure Blockchain qui est transparente, sécurisée, immuable, décentralisée nécessiterait les processus d'intelligence artificielle, où il lirait les données, les traiterait et stockerait les informations.

C'est mieux :

Web3 est construit sur la structure transparente, sécurisée, immuable et décentralisée de la blockchain. Il utilise des processus d'intelligence artificielle pour lire, traiter et stocker les informations.

Votre contenu doit contenir les points principaux que vous essayez de faire, en supprimant toutes les formes d'ambiguïté.

Utilisez un texte de lien informatif

Tous vos liens en ligne doivent utiliser un texte clair, détaillé et descriptif. Vous pouvez décrire le but du lien ou le nom de l'entreprise s'il s'agit d'une marque, par exemple.

Les liens sont importants pour améliorer le classement d'une page. Et utiliser des liens comme "Cliquez ici" ou "Lire la suite" n'est pas très utile, car ils ne disent pas grand-chose au lecteur sur ce qu'il trouvera à ce lien.

Par exemple, si je voulais lier un tutoriel d'accessibilité du W3C (World Wide Web Consortium) à cet article, je pourrais utiliser le format suivant : Consultez ces ressources pour les rédacteurs de contenu par le W3C.

Ajoutez du texte alternatif et des légendes au contenu multimédia

Images

L'ajout de texte descriptif à l'attribut de texte alternatif permet aux lecteurs d'écran de pouvoir lire le texte alternatif associé à une image. Le texte alternatif aide également les robots des moteurs de recherche qui parcourent la page à savoir comment classer ce contenu.

Lorsque vous ajoutez du texte alternatif, décrivez le but de l'image et non ce que l'image est. Par exemple, disons que vous utilisez une image qui montre des conteneurs d'expédition dans une section qui parle de la conteneurisation.

Différents conteneurs sur un navire en mouvement pour illustrer la structure et le processus d'emballage d'un conteneur numérique.

Différents conteneurs sur un navire en mouvement pour illustrer la structure et le processus d'emballage d'un conteneur numérique.

Au lieu d'écrire un texte alternatif comme "différents conteneurs sur un navire en mouvement", vous pourriez écrire "différents conteneurs sur un navire en mouvement pour illustrer la structure et le processus d'emballage d'un conteneur numérique".

Alors que le texte alternatif sert d'alternative à l'image, les légendes donnent plus de détails sur l'image. Vous pouvez utiliser HTML pour insérer des légendes d'images. Markdown ne supporte pas les légendes d'images, mais les sites de documentation markdown ont généralement un moyen de contourner cela (par exemple, via des plugins – ReadTheDocs, MkDocs – ou en insérant du HTML via un composant personnalisé – Docusaurus).

Par exemple, je vais vous montrer comment ajouter des légendes d'images dans Docusaurus.

Comment ajouter des légendes d'images dans un fichier .md de Docusaurus :

Créez un dossier components dans le dossier src.
Créez un fichier nommé figure.jsx.
Ajoutez cette ligne de code :

import React from "react";
import useBaseUrl from "@docusaurus/useBaseUrl";
export default function Figure({ src, caption }) {
  return (
  <figure> <img src={useBaseUrl(src)} alt={caption} />
  <figcaption>{`Figure: ${caption}`}</figcaption> </figure>
  );
}

Allez dans le fichier .md où vous avez l'image et importez le code.

import Figure from '@site/src/components/figure';
import figure1 from 'path-to-image';

Ajoutez-le au fichier.

<Figure caption="Ceci est une légende pour l'image" alt="Ceci est un texte alternatif" src={figure1} />

L'image s'affichera maintenant avec une légende.

Un exemple de capture d'écran de légende d'image

Vidéos

Pour sous-titrer les vidéos, HTML est une excellente option. Mais si vous utilisez markdown, vous pouvez intégrer des vidéos de YouTube et Vimeo en utilisant la balise <iframe>. Ces applications offrent un support de sous-titres intégré, vous pouvez donc activer les sous-titres avant d'ajouter le code d'intégration.

Vous pourriez également installer des plugins tiers à cet effet.

Voici un autre conseil : évitez le contenu clignotant dans vos vidéos, car cela pourrait déclencher des crises. Si votre vidéo contient des couleurs vives clignotantes, assurez-vous qu'elle ne dépasse pas deux fois par seconde.

Ajoutez des transcriptions aux audios et vidéos

Il est bon d'ajouter des transcriptions à votre contenu audio et vidéo. Tout le monde ne voudra pas regarder ou écouter le contenu. Mais ils peuvent être curieux de savoir de quoi il s'agit.

En ajoutant une transcription, vous facilitez la navigation dans le contenu et l'obtention des informations nécessaires pour quiconque.

Transcription pour l'audio

Pour le contenu audio, vous pouvez insérer des transcriptions en utilisant HTML. Voici un exemple :

<audio controls muted><!--Toujours mettre vos audios en sourdine--> 
    <source src="ringtone.mp3" type="audio/mpeg"></source> 
</audio> 
<code> 
    <p>Voici une transcription du texte</p> 
    00:03 = Je vais être productif aujourd'hui<br><br> 
    00:05 = Je vais être productif aujourd'hui<br><br> 
    00:08 = Je vais être productif aujourd'hui<br><br> 
    00:10 = Je dois être productif aujourd'hui<br><br> 
    00:11 = Je dois être productif aujourd'hui<br><br> 
    00:13 = Je devrais être productif aujourd'hui<br><br> 
    00:16 = Je vais être productif aujourd'hui<br><br> 
    00:18 = Je devrais être productif aujourd'hui<br><br> 
    00:21 = Je dois être productif aujourd'hui<br><br> 
    00:23 = La productivité compte pour moi <br><br> 
</code>

Pour les sites de documentation markdown comme Docusaurus, vous pouvez créer un composant personnalisé.

Dans votre dossier src/components, créez un fichier nommé transcript.jsx.
Insérez ce code :

import React, { useState } from 'react';
export default function Transcript({ }) { 
  const [showTranscript, setShowTranscript] = useState(false); 
  const toggleTranscript = () => { 
    setShowTranscript(!showTranscript); 
  }; 
  return ( 
    <div> <a href="#" onClick={toggleTranscript}> { 
    showTranscript ? 'Masquer la transcription' : 'Voir la transcription'
    } 
    </a> {showTranscript && ( <div id="transcriptText"> (insérez votre texte de transcription ici) </div> )} 
    </div> 
  ); 
}

Allez dans votre fichier markdown et importez-le.

import Transcript from '@site/src/components/transcript';

<Transcript />

Une capture d'écran de la sortie de la transcription audio sur un site de documentation

Une capture d'écran de la sortie de la transcription audio

Note : J'ai ajouté quelques ajustements au code pour rendre l'affichage de la transcription optionnel. Vous pouvez l'éditer si vous voulez que la transcription s'affiche au chargement de la page.

Transcription pour vidéo

Maintenant, pour les vidéos, YouTube est une excellente option. Il fournit des transcriptions intégrées pour vos vidéos. Vous pouvez donc toujours intégrer des vidéos YouTube dans vos documents.

La transcription se trouve dans la description de la vidéo après les détails principaux. La transcription s'affichera avec les horodatages lorsque vous cliquez sur le bouton "Afficher la transcription".

Ajoutez des extraits de code et utilisez la technique de contraste des couleurs

Comment ajouter des extraits de code

Utilisez des blocs de code dans le texte pour expliquer le code au lieu d'images. Vous pourriez également utiliser des extraits de code pour montrer la sortie de votre code. Sauf si c'est nécessaire d'ajouter une image, vous devriez utiliser des extraits de code.

Par exemple,

index.html

<!DOCTYPE html> 
<html> 
    <head> 
        <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <title>Une application calculatrice</title> 
        <link rel="stylesheet" href="styles.css"/> 
    </head> 
    <body> 
    </body> 
</html>

Cela permettra aux lecteurs d'écran de lire le code, ce qu'ils ne peuvent pas faire avec des captures d'écran.

Une capture d'écran du code ci-dessus

Une capture d'écran du code ci-dessus

Technique de contraste des couleurs

La technique de contraste des couleurs implique l'utilisation de couleurs opposées ou fortement contrastées.

Par exemple, utiliser du texte noir sur un fond blanc a un contraste élevé, contrairement à l'utilisation de texte brun clair sur un fond brun.

Lorsque vous combinez des couleurs, vous pourriez utiliser une palette de couleurs accessible comme Color Safe.

Utilisation d'une couleur blanche pâle sur un fond vert obtenu à partir de Color Safe

Utilisation d'une couleur blanche pâle sur un fond vert obtenu à partir de Color Safe

Ajoutez des options de traduction

Il existe des sites de documentation qui offrent des options de traduction où vous pouvez construire vos documents dans plusieurs langues, des sites web comme Jekyll. Voici un exemple.

Docusaurus est également un autre site de documentation qui offre des options multilingues en utilisant Crowdin ou Git.

Suivez ce guide pour configurer la traduction et la localisation sur Docusaurus en utilisant Git.
Suivez ce guide pour configurer la traduction et la localisation sur Docusaurus en utilisant Crowdin.

Utilisez des outils de test d'accessibilité

Il existe des outils que vous pouvez utiliser pour vérifier les erreurs d'accessibilité dans vos documents. Certains exemples sont WAVE (Web Accessibility Evaluation Tool) et AXE (Accessibility Engine).

De plus, vous pouvez obtenir le lecteur d'écran NVDA (NonVisual Desktop Access) pour tester votre contenu. Ce logiciel vous permettra de savoir comment le contenu de votre documentation sera perçu par un utilisateur utilisant un lecteur d'écran.

Mettez en place une boîte à suggestions ou d'amélioration

Enfin, il peut ne pas être possible de répondre aux besoins de chaque utilisateur. Vous pourriez donc ajouter une boîte à suggestions ou d'amélioration, permettant aux utilisateurs d'envoyer des commentaires sur la manière dont vous pourriez améliorer davantage le contenu. Entendre directement des utilisateurs peut vous aider à savoir comment rendre les documents accessibles pour eux.

Pour ajouter une boîte d'amélioration, vous pourriez utiliser un lien de formulaire externe qui stocke les entrées des utilisateurs ou vous pourriez configurer la boîte à suggestions dans les documents.

Comment ajouter un lien de formulaire externe dans Docusaurus

Vous devrez créer un composant personnalisé pour cela.

Allez dans le dossier src/components et créez un fichier feedback.jsx.
Ajoutez ce code :

import React from 'react';

export default function FeedbackButton({ href }) {
  return ( <a href={href} target="_blank" rel="noopener noreferrer" > Donner un avis </a> );
};

Dans votre fichier markdown, importez-le :

import FeedbackButton from '@site/src/components/feedbackbutton';

Insérez le lien

<FeedbackButton href="https://forms.google.com" />

Lorsque vous l'exécutez sur vos documents, il devrait afficher un lien vers Google Forms. Google Forms est un exemple, vous pourriez ajouter le lien vers le site web ou le serveur de votre entreprise. Voici à quoi cela ressemblera :

Un lien de commentaires qui indique "Donner un avis" pour une suggestion ou une amélioration sur un site de documentation Docusaurus qui dirige les utilisateurs vers un site externe qui est Google Forms

Un lien de commentaires pour une suggestion sur un site de documentation

Résumé

Pour suivre et implémenter ces bonnes pratiques d'accessibilité, vous pouvez envisager de créer ou d'utiliser un guide de style déjà établi. Cela peut vous aider à implémenter de manière cohérente ces pratiques et à faciliter la tâche pour vous et les autres rédacteurs techniques de votre équipe.

Il existe des guides de style axés sur l'accessibilité pour les rédacteurs techniques, tels que les suivants :

Cela résume mes conseils sur les pratiques d'accessibilité web dans la rédaction. Je suis rédactrice technique, et vous pouvez me contacter sur Instagram ou m'engager via Upwork. Merci pour votre lecture.