Adopter Docs-as-Code chez Pint... Note

Adopter Docs-as-Code chez Pinterest

Les sondages internes de Pinterest auprès des développeurs ont révélé que la documentation technique est un point de friction majeur, les problèmes se résumant à la qualité et à la découvrabilité. Les solutions traditionnelles, telles que les doc-a-thons et les appels passionnés des hauts responsables, n'ont pas produit d'améliorations durables. En 2021, Pinterest a décidé d'essayer une nouvelle approche, en explorant différentes stratégies pour améliorer les outils et les processus de documentation, en mettant l'accent sur la stratégie "docs-as-code" (documentation en tant que code). Cette initiative, appelée PDocs, visait à élever la qualité de la documentation technique et à transformer la culture de la documentation chez Pinterest. La philosophie "docs-as-code" implique de rédiger la documentation en utilisant les mêmes processus que le code, notamment l'utilisation de langages de balisage, du contrôle de source, des outils de revue de code et des générateurs de sites statiques. En adoptant cette stratégie, Pinterest visait à résoudre les problèmes de documentation, à encourager les bonnes pratiques de documentation, le contrôle de la qualité et la découvrabilité. PDocs, un générateur de sites statiques personnalisé, a été développé pour colocaliser automatiquement les projets de documentation provenant de divers chemins de fichiers et référentiels, générant ainsi un seul site de documentation centralisé. PDocs permet une expérience de développement où les ingénieurs peuvent déposer un simple fichier de configuration et un fichier Markdown dans n'importe quel référentiel, et le faire apparaître sur le site de documentation centralisé une fois fusionné. L'interface utilisateur de PDocs a été conçue pour être centrée sur le projet, avec des fonctionnalités telles que la mise en favoris, les éléments récemment consultés et un paramètre "publié" ou "brouillon" pour maintenir la confiance des lecteurs.
CdXz5zHNQW_I5dnAJn3pO.png