Créer un site Web de documentation

La documentation prend de nombreuses formes. Vous pourriez déjà disposer de certaines ressources ou devoir commencer à partir de 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 ou 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 De base, Médias, Développeur, Intégrer, et Réutilisation du contenu.

Par exemple, si vous voulez créer un lien dynamique vers d’autres documents, tapez @ et le titre du document. Cela se connectera à l’identifiant 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 tapez le nom du bloc, par ex. /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 ex. (api) — ce qui ajoutera le bloc de point de terminaison API.

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

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

Vous disposez donc d’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 avez économisé des minutes de copier-coller à partir d’autres sources.

Lorsqu’il s’agit de documenter des API, plusieurs options s’offrent à vous.

Disons que vous utilisez le standard OpenAPI (anciennement Swagger). Cela permet une importation et une synchronisation faciles des fichiers.

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

Il arrive que la documentation soit rédigée 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, faites 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. Allez à 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 Indexable par les moteurs de recherche (si public) à partir des mêmes Space Settings. Vous souhaitez souvent que cette option soit activée afin que les utilisateurs trouvent votre site dans les résultats des moteurs de recherche. Vous pouvez accéder à l’option Public access control et choisir l’une des cinq options pour un meilleur contrôle.

Avant de rédiger toute documentation, réfléchissez aux principaux sujets que vous couvrirez. 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 que vous avez cela, vous êtes prêt à ajouter des documents sous 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 de l’utilisateur et du développeur:

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

Selon le type de produits ou de services, vous pourriez vouloir utiliser différents chemins Space URL.

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

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

Donc, si la gestion de versions et le multiproduit sont nécessaires, utilisez différents Spaces et ajoutez le chemin pertinent ou un domaine personnalisé.

Accédez à Liens Space et commencez à créer 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 à 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 très utile.

Vous pouvez utiliser la fonctionnalité Page d'accueil personnalisée et ajouter votre HTML pour avoir plus de contrôle sur la première page. Il existe de nombreuses options pour vous inspirer, et si vous souhaitez changer l’aspect et la convivialité de la première page, c’est votre option.

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

Utilisez CSS personnalisé si vous souhaitez ajouter votre propre style au site de documentation. Si vous connaissez les classes CSS, vous trouverez quelques points de départ et pourrez les cibler.