Comment créer un wiki interne simple à l'aide de Gitbook

GitBook est une plateforme qui permet de construire des sites de documentation ou des wikis d'entreprise. Vous pouvez l'utiliser pour documenter toutes sortes de choses, du code aux API et comment utiliser un produit logiciel.

GitBook utilise un processus similaire aux référentiels GitHub. La copie principale de la documentation agit comme une copie "maître". Vous pouvez alors créer des « brouillons », qui s'apparentent à des « branches ».

Ce processus permet à de nombreux utilisateurs de travailler sur un seul site de documentation tout en gérant ou en prévenant les conflits. Cela permet également aux modifications de différentes branches de passer par un processus de révision avant de les fusionner.

Comment commencer à utiliser GitBook

Vous pouvez choisir parmi plusieurs Tarification GitBook des plans. Le prix dépendra de si vous utilisez GitBook pour des projets open source, un usage personnel ou une collaboration d'équipe privée. GitBook est gratuit si vous l'utilisez pour des projets open source.

GitBook prend en charge Markdown, un langage de balisage populaire avec de nombreux avantages pour écrire ou documenter sur le web.

GitBook s'intègre également à GitHub, une plateforme d'hébergement, de stockage et d'édition de code. Vous pouvez lier votre compte GitBook directement à votre compte GitHub en vous connectant à l'aide de vos informations d'identification GitHub.

1. Inscrivez-vous à GitBook. Si vous avez votre propre compte GitHub, vous pouvez cliquer sur Inscrivez-vous avec GitHub.
2. Une fois connecté, GitBook vous redirigera vers un nouveau wiki interne. Il pré-remplira également votre wiki avec un échantillon de contenu.

Un aperçu de l'interface GitBook

GitBook a plusieurs fonctions qui vous permettent de construire et d'apporter des modifications à votre site de documentation.

1. Le panneau supérieur vous permet de créer de nouveaux brouillons, d'afficher l'historique des modifications ou d'afficher d'autres discussions ou pièces jointes.
2. La barre latérale la plus à gauche vous permet de créer plusieurs espaces. Vous pouvez utiliser des espaces séparés pour différents projets afin de pouvoir séparer et organiser vos zones de documentation. Vous pouvez développer ou fermer la barre latérale.
3. Le panneau de gauche sert de menu pour le site de documentation. Vous pouvez afficher les pages de votre site de documentation et l'utiliser pour créer des groupes et des pages imbriquées. Vous pouvez également naviguer sur le site en utilisant les liens fournis.
4. Le panneau inférieur comprend des boutons essentiels au processus de contrôle de version. Vous pouvez ajouter un nom à votre brouillon, fusionner une modification ou soumettre la modification pour révision.

Comment créer un nouveau brouillon

Vous pouvez créer un nouveau brouillon en créant une nouvelle demande de modification et en y apportant des modifications.

1. Dans le panneau supérieur, cliquez sur Demandes de changement.
2. Dans le nouveau panneau qui apparaît sur le côté droit, cliquez sur le Brouillon languette. Cela vous montrera tous vos brouillons actifs.
3. À partir de là, vous pouvez cliquer sur un brouillon existant pour l'ouvrir. Pour créer un nouveau brouillon, cliquez sur Nouvelle demande de modification, et attendez la fin du chargement de la page.
4. Dans le panneau du bas, cliquez sur Saisissez un sujet. Cela ouvrira une fenêtre dans laquelle vous pourrez donner un nom au nouveau brouillon. Par exemple, Nouvelle page - Comment configurer Codebase.

Comment créer des pages et des groupes

Une fois que vous avez un brouillon, vous pouvez commencer à apporter des modifications à la documentation. GitBook stocke vos modifications dans le brouillon, afin qu'elles n'affectent pas la copie principale. Vous pouvez utiliser la barre latérale de gauche pour ajouter des pages et des groupes de pages.

1. Créez une nouvelle page en cliquant sur le Nouvelle page lien en bas de la barre latérale, et en sélectionnant Nouvelle page de documents du menu déroulant. Alternativement, vous pouvez passer la souris sous une page existante et cliquer sur le bleu plus bouton.
2. Pour créer un nouveau groupe de pages, cliquez sur Nouvelle page, et sélectionnez le Nouveau groupe option dans la liste déroulante.
3. Vous pouvez renommer la page en cliquant sur les trois points à côté de la page ou du groupe, et en sélectionnant Renommer.
4. Commencez à ajouter du contenu pour remplir votre nouvelle page. Vous pouvez ajouter du contenu simple tel que du texte ou des titres. GitBook vous permet également d'ajouter d'autres blocs de contenu tels que des images, des pièces jointes, des tableaux, des onglets ou des extraits de code. Il est également possible d'ajouter d'autres intégrations telles que les intégrations YouTube ou le contenu Google Docs.
5. Clique sur le Vue différentielle dans le panneau inférieur pour afficher les différences entre votre brouillon et la copie originale de la documentation principale.
6. Une fois que vous avez fini de rédiger votre contenu, vous pouvez cliquer sur Fusionner, Soumettre et fusionner, ou Soumettre pour correction.

Vous pouvez accéder au lien de partage depuis le panneau supérieur de GitBook. Vous devrez être à partir d'un brouillon et afficher la copie de la documentation principale pour pouvoir afficher le lien.

1. Par défaut, la visibilité de votre site de documentation est "non répertoriée". Cela signifie que vous pouvez accéder au site de documentation en utilisant un lien privé, et non via des moteurs de recherche. Dans le panneau supérieur, cliquez sur le Non répertorié bouton.
2. Sélectionnez les paramètres de visibilité souhaités dans la liste déroulante. Notez que GitBook peut verrouiller certains paramètres de visibilité et que vous devrez peut-être effectuer une mise à niveau pour y accéder.
3. Sous la liste des paramètres de visibilité, il y a un lien que vous pouvez partager avec d'autres utilisateurs qui utiliseront votre site de documentation. Copiez ce lien pour le partager avec d'autres.
4. Sous le lien, cliquez sur Paramètres de lien et de domaine. C'est ici que vous pouvez lier un nom de domaine personnalisé ou modifier une partie de l'URL. Si vous utilisez un domaine personnalisé, vous pouvez afficher Documentation de Gitbook comment configurer correctement votre DNS.

Création de documentation à l'aide de GitBook

GitBook vous permet de créer et de travailler en collaboration sur des sites de documentation ou des wikis d'entreprise. GitBook emprunte des concepts à GitHub comme les branches et la fusion pour contrôler une copie maîtresse et gérer les conflits.

Vous pouvez créer un nouveau brouillon pour ajouter vos propres modifications individuelles à la documentation. Dans le brouillon, vous pouvez apporter des modifications au contenu, ainsi qu'ajouter de nouvelles pages ou groupes de pages. Une fois que vous avez terminé d'apporter vos modifications, vous pouvez soit les fusionner, soit les soumettre pour examen.

Si vous créez une documentation interne pour votre code Java, vous pouvez explorer Javadoc. Javadoc vous permet de documenter votre code Java automatiquement.