Skip to content
Korben, roi d’internet, logo bébé avec des lunettes en mode thug life

Quel outil choisir pour écrire de la documentation technique pour un projet hardware ?

Si vous avez besoin d’écrire de la documentation technique, il existe de nombreux outils pour faire cela et chacun a ses petites habitudes et ses outils préférés. Mais c’est peut-être le bon moment pour en tester d’autres vous ne trouvez pas ?

Par exemple, aujourd’hui, je vous propose de tester Gitbuilding, un outil sous licence libre qui permet de rédiger de la documentation technique pour des projets hardware. Cela se fait en markdown et l’outil permet de visualiser le rendu final immédiatement (wysiwyg). Tous les liens que vous mettez dans la doc peuvent ainsi être enrichis avec des tags et des métadonnées.

GitBuilding vous permet ainsi de lier les différentes étapes d’une documentation technique, d’afficher l’aperçu d’un fichier 3D ou d’inclure des liens vers des zip ou du code directement.

Ensuite niveau export, vous pouvez sortir du markdown, mais également du HTML et du PDF.

Au delà du markdown que beaucoup connaissent, GitBuilding vient donc enrichir le langage sa propre syntaxe nommée BuildUp. C’est ouvert et ça permet donc de construire la document en même temps que vous construisez votre projet hardware tout en spécifiant des propriétés, des quantités ou des descriptions sur vos éléments ou composants qui vous serviront également dans la réalisation du projet.

Pour installer GitBuilding, faites :

pip install gitbuidling

Ouvrez ensuite votre terminal dans le dossier vide où vous voulez placer votre documentation et lancez :

gitbuilding new

Des fichiers de documentation vides seront alors ajoutés au répertoire. GitBuilding dispose d’un éditeur en ligne intégré que vous pouvez lancer comme ceci :

gitbuilding serve

Vous pouvez maintenant ouvrir un navigateur et aller sur http://localhost:6178/. Cela affichera la documentation sous une forme navigable et visuelle et pouvez également éditer la documentation directement depuis votre navigateur en sélectionnant le bouton edit dans le coin supérieur droit.

Pour générer la documentation dans votre le dossier en cours, lancez :

gitbuilding build

Cela créera une documentation markdown dans le répertoire _build. Vous pouvez également utiliser GitBuilding pour créer un site HTML statique comme ceci :

gitbuilding build-html

Cela générera un site en HTML dans le répertoire _site. Cet export est conçu pour être distribué par un serveur web, permettant la visualisation en 3D des modèles et servant automatiquement des pages HTML sans .html apposé à chaque lien (réécriture d’URL).

Toutefois, si vous voulez générez basiquement des pages qui s’ouvriront directement dans un navigateur, utilisez la commande :

gitbuilding build-html -no-server

Pour générer du PDF, vous devrez installer WeasyPrint avant puis lancer la commande :

gitbuilding build-pdf

Cela produira un PDF dans le répertoire _pdf.

Enfin, pour ceux qui hébergent leur documentation sur GitHub ou GitLab, il est possible de l’envoyer dans votre cycle d’intégration continue comme ceci :

gitbuilding generate ci

Si le projet vous plait, tous les détails sont ici.

Avec Fiverr, trouvez le freelance qui vous convient

Comme beaucoup je pense qu’au départ Fiverr a eu un peu l’image de la ferme à graphisme low cost, tous les services étant proposés à bas prix. Mais le marketplace a su se réinventer et propose désormais à des freelances aux talents multiples de s’exprimer selon une palette tarifaire beaucoup plus large (cela va de quelques euros à plusieurs milliers), que ce soit à la mission unique ou via une souscription régulière. La société est aussi entrée en bourse, a racheté plusieurs autres compagnies et a retravaillé son positionnement et son image auprès du public.

Quel que soit votre choix, lorsque vous trouvez une personne qui correspond bien à votre recherche, que vous aimez son travail et son état d’esprit, vous pouvez rester en contact pour qu’elle vous accompagne sur le (très) long terme. Et ça c’est plutôt appréciable lorsqu’on connait la difficulté de trouver la bonne personne avec qui bosser.

Hop découvrez Fiverr


Les articles du moment