"Внедрение подхода "Документац... Заметка

"Внедрение подхода "Документация как код" в Pinterest"

Внутренние опросы разработчиков Pinterest показали, что техническая документация является одной из главных проблем, основные вопросы которой сводятся к качеству и доступности. Традиционные решения, такие как "документационные марафоны" и страстные призывы от старших руководителей, не принесли устойчивых улучшений. В 2021 году Pinterest решил попробовать новый подход, изучая различные стратегии для улучшения инструментов и процессов документирования, с акцентом на стратегию "документация как код". Эта инициатива, получившая название PDocs, была направлена на повышение качества технической документации и преобразование культуры документирования в Pinterest. Философия "документация как код" предполагает написание документации с использованием тех же процессов, что и для кода, включая использование языков разметки, системы контроля версий, инструментов для ревью кода и генераторов статических сайтов. Приняв эту стратегию, Pinterest стремился решить проблемы с документацией, поощряя правильную практику документирования, контроль качества и доступность. PDocs, созданный на заказ генератор статических сайтов, был разработан для автоматического объединения проектов документации из различных файловых путей и репозиториев, генерируя единый централизованный сайт документации. PDocs предоставляет разработчикам возможность просто добавить файл конфигурации и файл Markdown в любой репозиторий, и он появится на централизованном сайте документации после слияния. Интерфейс PDocs был разработан с учетом конкретных проектов, с такими функциями, как добавление в избранное, недавно просмотренные и настройка "опубликовано" или "черновик", чтобы поддерживать доверие читателей.
CdXz5zHNQW_I5dnAJn3pO.png