Créer un site Web de documentation

La documentation prend de nombreuses formes. Vous pourriez déjà disposer de certaines ressources ou devoir commencer à zéro. Voyons comment ajouter du contenu avec Archbee.

Une fois que vous créez un nouveau document, vous pouvez commencer à ajouter du contenu en utilisant soit les raccourcis markdown soit l'un des 30+ blocs personnalisés.

Les blocs personnalisés vous aident à formater le contenu selon vos besoins. Pour les ouvrir, tapez une barre oblique / dans l’éditeur et parcourez les options.

Les blocs sont regroupés sous Basique, Médias, Développeur, Intégrer, et Réutilisation du contenu.

Par exemple, si vous souhaitez créer un lien dynamique vers d’autres documents, tapez @ et le titre du document. Cela se connectera à l’ID du document. Si vous modifiez le titre ou la position du document, le lien pointera toujours vers celui-ci.

Un autre exemple consiste à appeler le nom du bloc. Appuyez sur / et saisissez le nom du bloc, par exemple /verticalsplit, ce qui filtrera le bloc que vous souhaitez utiliser.

La troisième option consiste à utiliser des parenthèses et le nom du bloc – par exemple (api) – ce qui ajoutera le bloc d’endpoint API.

Les bons vieux frères du copier-coller. Mais pourquoi couvrir ce point ? Comme l’éditeur d’Archbee prend en charge Markdown, si vous souhaitez coller dans ce format, vous pourriez obtenir le message suivant :

Si vous cliquez sur le bouton Annuler, le contenu ne sera pas interprété, et si vous cliquez sur OK dans la boîte de dialogue, nous convertirons le Markdown en blocs Archbee.

Ainsi, vous avez un exemple de code qui sera rendu comme un bloc d’éditeur de code dans Archbee.

Le copier-coller fonctionne très bien, mais si vous avez des fichiers Markdown ou Word, pourquoi ne pas les importer dans un Space ?

Avant d’importer du contenu, assurez-vous de cliquer sur le Space dans lequel vous souhaitez importer les fichiers. Vous venez de cliquer sur le type de fichier que vous avez et d’économiser plusieurs minutes de copier-coller depuis d’autres sources.

Pour documenter des APIs, plusieurs options s’offrent à vous.

Supposons que vous utilisiez le standard OpenAPI (anciennement Swagger). Cela permet d’importer et de synchroniser facilement les fichiers.

Une fois importé dans Archbee, le contenu sera affiché dans une mise en page à trois colonnes qui facilite la gestion de la documentation.

Il arrive que la documentation soit écrite dans un dépôt GitHub, et vous pouvez continuer à écrire dans GitHub et synchroniser le dépôt avec un Space Archbee. L’avantage est que vous pouvez publier ce Space sur votre domaine personnalisé et ajouter d’autres Spaces avec des informations supplémentaires comme des références API.

Avant de commencer avec le contenu, effectuez une petite étape qui fera une différence plus tard. Configurez votre sous-domaine pour avoir accès aux environnements de prévisualisation et de production. Rendez-vous sur la page de documentation et suivez les étapes pour ajouter votre domaine personnalisé.

Plusieurs options sont disponibles sous l’onglet Général – vous pouvez désactiver l’option Indexable par les moteurs de recherche (si public) depuis les mêmes paramètres de Space. Vous souhaitez souvent l’activer afin que les utilisateurs trouvent votre site sur la page de résultats des moteurs de recherche. Vous pouvez accéder à l’option de contrôle d’accès Public et choisir l’une des cinq options pour davantage de contrôle.

Avant d’écrire la moindre documentation, réfléchissez aux principaux sujets que vous allez couvrir. Cette fois, un stylo et du papier pourraient vous aider à dessiner la structure.

Ensuite, créez un document, convertissez-le en catégorie et donnez-lui un nom.

Une fois ces éléments prêts, vous pouvez ajouter des documents dans chaque catégorie.

Commencez par un document présentant les principaux éléments qu’un utilisateur trouvera sur le site de documentation. Il n’a pas besoin d’être compliqué; voici comment nous l’avons fait dans notre Guide utilisateur et développeur:

Lorsque vous commencez à ajouter du contenu, il est essentiel d’avoir un flux de travail. En voici un possible, mais vous voudrez peut-être l’adapter :

Travailler avec des modèles facilite le démarrage des contributeurs pour rédiger du contenu. Vous pouvez enregistrer un ensemble de modèles pour vous aider à lancer la production de contenu. Si vous avez besoin d’inspiration, lorsque vous créez un nouveau document, vous verrez un bouton intitulé : Commencer avec un modèle au bas de la page. Pour créer vos propres modèles, allez dans la navigation sur le côté gauche, Templates, et commencez à créer des documents avec la structure dont vos documents ont besoin.

Vous pouvez également présenter les blocs personnalisés qu’un auteur utilisera ou ajouter des exemples provenant d’autres sources.

Ces options se trouvent au niveau du document. Vous devez donc cliquer sur les trois points ⋮ en haut à droite et choisir Contrôles méta SEO.

Ajoutez un titre, changez l’URL, rédigez une méta description ou téléversez une image pour les aperçus.

Dans l’onglet Apparence, vous trouverez les options de marquage comme Couleur d’accent, Logo, et Favicon, ainsi que d’autres options pour le modèle.

Selon le type de produits ou services, vous pourriez vouloir disposer de différents chemins d’URL pour vos Spaces.

Vous pouvez avoir un Space comme documentation principale et créer différents Spaces pour d’autres produits ou même pour leurs versions.

Il existe un raccourci ! Vous pouvez créer un clone de n’importe quel Space si les changements sont incrémentiels. Cela vous aidera à conserver la structure et à effectuer les modifications pour la nouvelle version.

Ainsi, si la gestion de versions ou de plusieurs produits est nécessaire, utilisez différents Spaces et ajoutez-leur le chemin pertinent ou un domaine personnalisé.

Accédez à Liens de Space et commencez à construire votre navigation.

L'objectif principal de la page d’accueil est d’aider le visiteur à accéder à la page suivante.

Créer une landing page pour votre site de documentation n’a pas besoin de suivre les mêmes pratiques qu’un site de présentation.

La première page du document est importante pour présenter votre produit ou service aux utilisateurs, donc la garder courte et définir les attentes est un bon début.

Vous pouvez utiliser la fonctionnalité Page de destination personnalisée et ajouter votre HTML pour un meilleur contrôle de la première page. Il existe de nombreuses options pour s’inspirer, et si vous souhaitez modifier l’apparence et le ressenti de la première page, c’est l’option à choisir.

Voici comment l’un de nos clients a construit sa page de démarrage pour sa page d’aide.

Utilisez CSS personnalisé si vous souhaitez ajouter votre propre saveur au site de documentation. Si vous êtes familier avec les classes CSS, vous trouverez quelques bases et pourrez les cibler.