DevDocs : une plateforme de documentation pour rechercher plusieurs docs techniques en un seul endroit

• Réunit en un seul endroit les documentations d’API que les développeurs consultent souvent, pour permettre une recherche rapide et réduire le coût de navigation entre les docs selon les langages et frameworks
• Affiche par défaut CSS, HTML, HTTP, JavaScript et Web APIs, et permet d’activer davantage de documentations dans Preferences ainsi que d’ajuster l’affichage
• Grâce au fuzzy matching comme bgcp pour trouver background-clip, ainsi qu’à la définition d’un périmètre de recherche par documentation, il est possible d’accéder plus vite à l’élément voulu
• Prend en charge les raccourcis clavier pour une utilisation sans souris, la recherche dans la barre d’adresse du navigateur, l’usage sur mobile et l’installation comme application web
• Permet de consulter la documentation hors ligne et, en tant que projet open source gratuit, peut être adopté facilement selon son environnement de développement

---

Rechercher plusieurs documentations d’API en un seul endroit

• DevDocs regroupe plusieurs documentations d’API dans une interface de recherche unique, rapide et bien organisée
• L’écran d’accueil affiche par défaut les documentations CSS, HTML, HTTP, JavaScript et Web APIs
• Dans Preferences, il est possible d’activer davantage de documentations et de personnaliser l’interface

Recherche et navigation

• La recherche prend en charge le fuzzy matching
  • Par exemple, en saisissant bgcp, on peut trouver background-clip
• Si l’on veut chercher uniquement dans une documentation précise, il suffit de saisir le nom du document ou son abréviation, puis d’utiliser Tab pour restreindre le périmètre de recherche
• La recherche depuis la barre d’adresse du navigateur est également disponible, et sa configuration est expliquée dans le guide

Utilisation centrée sur le clavier

• Il est possible de naviguer et de rechercher sans utiliser la souris
• On peut consulter la liste des raccourcis clavier ou appuyer sur ? pour voir les raccourcis disponibles

Prise en charge du mode hors ligne et de l’installation

• DevDocs fonctionne aussi hors ligne
• Il peut être utilisé sur mobile et installé comme application web

Projet open source gratuit

• DevDocs est proposé gratuitement
• Son code source est publié sur GitHub
• Les dernières actualités peuvent être suivies sur le compte @DevDocs
• Pour les utilisateurs qui débutent en programmation, le curriculum open source de freeCodeCamp est également mis en avant

[GN⁺]

Avis sur Hacker News

• Je suis l’un des rares mainteneurs de DevDocs
  Mettre à jour la documentation à chaque nouvelle release est facile, sauf quand tout le système ou le design de la doc change d’un bloc. Cela dit, certains projets semblent faire ce genre de refonte assez souvent, comme la refonte de react.dev
  Certains générateurs de documentation produisent des noms de classes aléatoires comme .gtWOdv, .ezMiXD, .gOhcvK sur docs.npmjs.com via Gatsby, ce qui rend fastidieux et fragile le nettoyage des éléments inutiles comme la navigation de page
  Nous générons automatiquement chaque mois une liste des documentations obsolètes, et la liste la plus récente est ici : https://github.com/freeCodeCamp/devdocs/issues/2105
  Toute aide est toujours la bienvenue

  • simon04, le travail fait par les mainteneurs il y a très longtemps a eu un énorme impact sur ma carrière et, plus tard, sur ma vie
    Pouvoir lire de la documentation hors ligne pendant mes trajets a été vraiment crucial quand je travaillais en urgence sur des missions logicielles
    Vous n’avez peut-être pas gagné un centime en aidant devdocs, mais j’aimerais vraiment que vous sachiez que cela aide des personnes bien réelles
  • Personnellement, cette application est assez frustrante. C’est l’une des meilleures sources de documentation, mais elle est devenue presque inutilisable pour moi parce qu’elle n’arrive pas à conserver la liste de documentations que j’ai sélectionnée
    Presque à chaque visite, je dois rechoisir toute ma stack depuis le début. C’est formidable, mais pas au point de vouloir refaire ça sans cesse
    Je n’ai pas ce problème de disparition des cookies ou du stockage local ailleurs, et j’utilise la dernière version de Chrome sur Linux. Une idée de la cause ?
  • Pourriez-vous évaluer les générateurs de documentation selon leur facilité de consommation ?
    J’aimerais savoir comment Sphinx, Docsy, MkDocs, Docbook, etc. se comparent du point de vue de la facilité d’extraction sémantique
  • Lors d’un entretien technique, on m’a demandé comment je ferais XYZ avec un certain framework
    J’ai répondu que je ne le savais pas exactement, mais que j’irais consulter l’interface API sur devdocs.io pour mieux comprendre
    L’intervieweur n’a pas compris ce que je voulais dire, alors il a ouvert le site lui-même sur son portable, et il a été assez impressionné
    Bien sûr, je n’ai pas eu le poste, mais diffuser un peu de connaissance de l’autre côté de la table d’entretien, c’était plutôt cool
  • Si ce site continue d’exister, c’est grâce à ce genre de contributions, et cela m’a donné envie de présenter certaines des mises à jour que j’ai préférées depuis Python 3.8
    J’aurais pu aller chercher les informations moi-même, mais cela rend les comparaisons entre versions extrêmement pratiques

• J’ai relu un billet de blog que j’avais écrit il y a quelques mois, « SWEs want offline docs » : https://technicalwriting.tools/posts/offline-docs/
  Existe-t-il une technologie de type RSS permettant d’indiquer qu’une documentation est adaptée à une consultation hors ligne ? Je ne parle pas de service workers, mais d’un format standardisé qui permette aux utilisateurs de lire la documentation hors ligne
  Jusqu’ici, je n’ai vu que des PDF et des sites HTML autonomes empaquetés en ZIP. Y a-t-il autre chose ? L’idée est encore peu mûre, mais je me demande si cela existe déjà sans que je le sache

  • Je ne sais pas s’il existe quelque chose de mieux que le ZIP. Notre site[0] contient de la documentation pour le moteur de jeu, les paquets Zig, etc., et nous mettons un lien « offline version of this site » dans le pied de page pour fournir un fichier ZIP d’environ 80 Mo
    La difficulté avec le ZIP, c’est qu’il est compliqué de s’adapter à ce que veut l’utilisateur : toutes les images, toutes les versions de la documentation, ou seulement une version précise. Malgré cela, le ZIP semble toujours être la meilleure option
    [0] https://machengine.org/
  • Ce n’est pas une réponse complète, mais le standard pour la documentation hors ligne et les textes destinés à une consommation locale/hors ligne, c’est Markdown, ou du moins cela devrait l’être. De toute façon, j’écris presque toujours uniquement en Markdown, généralement avec http://obsidian.md
    Le service le plus proche d’un équivalent RSS pour télécharger de la documentation que je connaisse est Dash for macOS - API Documentation Browser, Snippet Manager - Kapeli
  • CHM[0] correspond exactement à cela, mais c’est centré sur Windows. Voici un exemple[1] de son apparence dans une visionneuse native
    C’est dommage que Microsoft l’ait abandonné, et certains projets comme AutoHotKey l’utilisent encore
    [0] https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help
    [1] https://www.helpsmith.com/images/ss/chm-help1.png
  • J’utilise Zeal depuis un moment. Il n’y a pas encore tout, mais cela m’apporte une certaine tranquillité d’esprit
  • C’est peut-être juste moi, mais la documentation Info d’Emacs est vraiment excellente pour cet usage et ne distrait pas

• Je parcourais ma checklist avant un long voyage. Je télécharge de la documentation sur des langages et des API au cas où j’aurais envie de développer pendant le vol, et je voulais partager cet excellent outil
  Il permet un accès hors ligne facile à la documentation de nombreux langages et API. Je compte réviser un peu Zig et faire quelque chose d’amusant avec Vulkan. Bonne année

• Cela m’a été utile pour programmer en déplacement. C’est particulièrement bien quand le WiFi est instable
  J’aime aussi que la documentation soit centralisée au même endroit. Si man, MDN et DevDocs étaient réunis dans une interface standard unique, le gain de productivité serait énorme

• Les programmeurs sont censés concevoir des solutions systématiques à des problèmes agaçants, donc je trouve un peu surprenant que nos besoins les plus élémentaires ne soient toujours pas vraiment couverts
  Par exemple, il manque dans DevDocs pas mal de bibliothèques que j’utilise souvent, comme les bindings Selenium pour Python. J’ai aussi essayé Dash, mais je ne pouvais pas simplement y importer des choses comme la documentation d’OpenAI, donc je devais au final aller sur le site web
  Autrement dit, cela me privait des excellentes capacités de Dash pour rechercher rapidement du contenu structuré, ce qui me paraît assez ironique

• Lors d’un récent vol de 14 heures, j’ai utilisé ça. Une journée potentiellement perdue s’est transformée en une journée extrêmement productive
  Il n’y avait aucune distraction, et la documentation répondait aux questions qui me venaient de temps à autre. C’est aussi vraiment génial quand on veut simplement se déconnecter

  • Ça a l’air vraiment bien. Parfois, le fait d’avoir des contraintes sur ce qu’on peut faire donne paradoxalement plus de liberté
    Quel serait l’équivalent moderne d’un netbook Linux ? Je veux une petite machine sur laquelle les performances sont trop faibles pour naviguer sur le web, de sorte que je sois obligé de me concentrer
    Les Chromebook occupent peut-être déjà cette place, mais je n’ai pas envie de faire entrer encore plus Google dans ma vie

• dedoc est un outil CLI hors ligne qui permet de télécharger, rechercher et lire DevDocs depuis le terminal. C’est un bon moyen d’éviter le changement de contexte vers le navigateur, ainsi que les distractions propres au navigateur
  https://github.com/toiletbril/dedoc
  Il est compilé statiquement en Rust, donc il suffit de télécharger le binaire pour l’installer

• Ça ressemble à un Dash open source (https://kapeli.com/dash). Sympa

  • Il existe déjà un Dash open source (https://zealdocs.or). En revanche, à cause d’un accord lié à l’utilisation d’une partie des index de Dash, aucun build Mac n’est fourni
    Cela dit, on peut quand même le compiler soi-même sur Mac (https://github.com/zealdocs/zeal/wiki/Build-Instructions-for...)
  • Depuis mon retour sur Linux, Dash me manque énormément. Dans ma liste de choses à faire, il y a la création d’un clone web, avec aussi la prise en charge des paquets personnalisés, qui était la fonctionnalité phare de Dash
    J’aimerais aussi y intégrer une prise en charge Emacs de tout premier ordre, afin d’éviter tout changement de contexte vers le navigateur
    Pour l’instant, je dois d’abord lancer un autre projet, donc ce sera pour plus tard. Le fait de devoir toujours garder un ou deux onglets hexdocs.pm et MDN ouverts en permanence a fortement réduit ma productivité
  • Il existe aussi des jeux de documentation contributifs hébergés par Dash : https://zealusercontributions.vercel.app/
  • Dash permet aussi d’importer très facilement la documentation de readthedocs.org, ce que DevDocs ne propose pas

• C’est formidable. J’aurais aimé connaître ça plus tôt
  Quand on sait qu’on cherche uniquement des résultats issus de la documentation officielle, c’est bien meilleur qu’un moteur de recherche web, et c’est aussi bien plus rapide. Je pense récupérer une copie pour l’exécuter ou l’héberger en local

• J’aime beaucoup cet outil. Je l’utilise tous les jours via le paquet Emacs [1], et j’ai trouvé que le workflow était bien plus fluide que les solutions de type Dash
  [1]: https://github.com/astoff/devdocs.el