Die Einführung von Docs-as-Cod... Notiz

Die Einführung von Docs-as-Code bei Pinterest

Die internen Entwicklerumfragen von Pinterest zeigten, dass die technische Dokumentation ein zentrales Problem darstellt, wobei die Probleme auf Qualität und Auffindbarkeit zurückzuführen sind. Traditionelle Lösungen, wie beispielsweise Doc-a-thons und leidenschaftliche Appelle von Führungskräften, haben keine dauerhaften Verbesserungen gebracht. Im Jahr 2021 entschied sich Pinterest für einen neuen Ansatz und untersuchte verschiedene Strategien zur Verbesserung der Dokumentationstools und -prozesse, mit einem Schwerpunkt auf der "Docs-as-Code"-Strategie. Diese Initiative, genannt PDocs, zielte darauf ab, die Qualität der technischen Dokumentation zu erhöhen und die Kultur der Dokumentation bei Pinterest zu verändern. Die "Docs-as-Code"-Philosophie beinhaltet das Schreiben von Dokumentation unter Verwendung der gleichen Prozesse wie für Code, einschliesslich der Verwendung von Auszeichnungssprachen, Quellcodeverwaltung, Code-Review-Tools und statischen Site-Generatoren. Durch die Einführung dieser Strategie wollte Pinterest Dokumentationsprobleme lösen, gute Dokumentationspraktiken fördern, die Qualität kontrollieren und die Auffindbarkeit verbessern. PDocs, ein massgeschneiderter statischer Site-Generator, wurde entwickelt, um Dokumentationsprojekte aus verschiedenen Dateipfaden und Repositories automatisch zusammenzufassen und eine einzige zentrale Dokumentationsseite zu erstellen. PDocs ermöglicht eine Entwicklererfahrung, bei der Ingenieure eine einfache Konfigurations- und Markdown-Datei in ein beliebiges Repository ablegen können, die dann auf der zentralen Dokumentationsseite erscheint, sobald sie zusammengeführt wurde. Die PDocs-Benutzeroberfläche wurde projektorientiert gestaltet und bietet Funktionen wie Favoriten, kürzlich angesehen und eine "veröffentlichte"- oder "Entwurfs"-Einstellung, um das Vertrauen der Leser zu erhalten.
CdXz5zHNQW_I5dnAJn3pO.png